Helping with documentation is easy!


#1

Hi

Documentation has some issues problems and needs more people to fix it.

One of the problems is how to test the documentation before doing a merge request.

I have created a docker image that makes it easy. Just install docker and run:

docker run -d -it -p 8080:80 --name grav -v $HOME/the/place/you/have/documentation:/usr/share/nginx/html/user/pages elmanytas/ahumaro-grav-hifi

Then go to http://localhost:8080

Here is the webpage: https://hub.docker.com/r/elmanytas/ahumaro-grav-hifi/

Happy documenting!


#2

Sounds like you need a documentation team.
SL had one and they dumped them.


#3

I updated the grav docker image here:

https://hub.docker.com/r/elmanytas/hifi-grav/

Happy documenting!


#4

While I really appreciate your effort to start documenting and I told you HF really needs it, I must tell you that this way of helping documenting is really impossible for normal people to join in :frowning:

Under Windows for instance, trying to follow your instructions is hugely impracticable and should be instructed in a different way (I tried it now and was not able to have all the things running even after 1 hour or dockering).

I’m suspecting that you had in mind a Unix user (possibly MacOS), which is definitely not the normal user in Europe or at least where I live in Italy.

The pull request system from github can be interesting but still too nerdy for ordinary people to follow.

Did I already say that this is unnecessarily too complex? What about setting up a wiki where people can help even from mobile devices when they are waiting for the bus?

Also if your concern is having approved revisions, why not use wikimedia with this extension? https://www.mediawiki.org/wiki/Extension:Approved_Revs

If you are willing to go on with that docker + git pull + other things, you are ultimately looking for people working free for you which will not be the case. Wikipedia showed that it is instead possible to have a crowdware solution of people doing it as a hobby.


#5

The issue was that in the past, the docs was based on a wiki system, but it wasn’t really updated at all then.

Also, I’ve done PRs in the past for documentation, and they tend to sit there for awhile, so I tend to not do them often. I guess I could focus on more byte sized PRs and hope for the best, but the JSDocs system was supposed to help in the API department (which seems to be hit and miss).


#6

This is why I suggested an effective documentation team guiding the uses on documenting and really alive and proactive should be needed. A wiki without a management is always destined to chaos. What is interesting here is that a managed complex system like it is now without a wiki and with git pullrequests is proving to have produced a documentation which is currently C--------- (C with a lot of minuses, not really insufficient, but far from really usable).
It works well for a demo or with very skilled and nerdy uses, but completely inefficient for non nerdy people.

So a question arises here. Is this direction (being a 100% nerdy thing) the direction HiFi is willing to follow?
If so it is quite difficult to follow it by the majority of interested users. And it is not easily adaptable for educational purposes, I am trying to do. Maybe other platforms can become available with less learning curve. It’s a pity however, HiFi was almost there. :slight_smile:


#7

I think that I understand your point of view and some time ago I agreed with you, but not now.

Using github allow to manage docs as code and IMHO is better than have the content in a closed database in somewhere.
In github the content is really open and you can download, clone, modify and suggest changes.

Cloning a repository and doing a merge request is too hard? Everybody can open an issue here: https://github.com/highfidelity/hifi-docs-grav-content/issues

This is not a High Fidelity invention. A lot of enterprises use this way to document their projects and allow people to request changes:

Some tips about me:

  • I am not part of High Fidelity team.
  • In the enterprise where I work, in Spain, Windows computers are only a 10%. The other 90% are Linux (70%) and Mac (20%) aproxymately.
  • Maybe I am a bit nerd. :wink:

#8

I repeat myself. I am not against Github it is really a fantastic invention and if it werent there we should invent it again.

I was lamenting that this particular way of submitting documentation, involving the setup of a docker for having a visual feedback on it is not exactly the easy way as it was proposed in the title of this topic.

I am indeed very positive on this, and asking in my first post if you can provide explicit documentation on setting all this on a Windows machine, where docker support is not so easy to install and handle.

Also I would still stand with the point that much of the luck of the SecondLife documentation laid on the cooperative way of submitting documentation which could be done by any casual person even not committed to industrial IT standards.

Regarding myself, I work as a professional Java programmer, so github and Linux and other things are not by themselves an obstacle to me, but being also an educator to non technical people AND to professional lazy IT people, I can confirm that every complexity in the workflow can be used as an excuse for not helping.

It can be quite different if this would be a paid remote job. In such case obviously what you wrote makes a lot of sense.

Where I work in Italy, 80% of programmers do use Windows including myself for developing, and we use virtual machine and docker for running our products, but majority of people find Windows on desktop much more productive than Linux. Myself, I have MacOS, Linux and Windows machines and work on all of them without particular problems, but for instance to use virtual worlds Windows is still the best choice and with vr is the only choice.


#9

EUREKA!

I figured this may work, and I just gave it a test!

If you use Visual Studio Code, you do NOT need to use Docker to have a preview! You can also do all commits and branch management directly from VS Code as well! This may be my new go-to method of updating the docs and my own GitHub repositories.

In addition, a fresh install of Visual Studio Code is all you need, along with a git manager of your choosing.

EDIT: This does not allow you to edit the API-Reference, as that is auto generated. However, all other parts of the documentation are fully editable using this method.


#10

Looks like Atom also have a preview function but Visual Studio Code could be a better choice for Windows users:

Maybe we can do a more detailed guide to non technical users helping them to modify docs. I think here is the right place to upload it: https://docs.highfidelity.com/write-for-us/contribute


#11

Also, for Visual Studio (i.e., not Code) there’s at least one extension that does MD preview: “Markdown Editor” by Mads Kristensen.


#12

Irony dr evil easy meme wont load cos science