As you’ve probably noticed our documentation is pretty scattered and somewhat incomplete. I thought it would be good to put out the following request:
If you’d like to help out with the project and are willing to spend the time needed, would you be willing to be the documentation czar? Duties would include:
Scan through this forum to find the many great threads where people have attempted part of the documentation task
Scan through the docs in meshtastic-device/docs
Scan through letstalkthis
Scan through a great android doc by @qurm (I can find the link if someone is willing)
Merge/edit all of the above into either wiki pages on github or a tree of .md files (your preference) to be the “official documentation”
Delete all the other locations (for anything that you moved into your new pretty docs) and provide a link to your new doc.
Skills needed:
Being slightly comfortable with github/git (or willing to learn)
Basic experience with words
‘Drive’ the doc process at least well enough to get this initial push completed
(no programming background needed!)
Once you’ve done this ideally we’d have four trees of docs:
Project overview
Developer docs
Python commandline user guide - (I’d change the tool to link to this doc for --help)
Android user guide (I’d change the android app to add a help button linking to your doc)
In looking for examples, I’ve been very impressed with the Raspberry Pi documentation. It’s quite thorough, deals with hardware & software, and all the docs are hosted on Github for easy pull request changes. Though I don’t believe they are hosted by github pages, so I’m not sure what service they point at the documentation repo.
I think that it could be a good model to look at. Does anyone else know of other good documentation examples? I don’t love the UI of RPIs site, but the layout of the repo is very nicely done. That’s easy enough to change once we have all the material up there. Some CSS whiz could be of help there.
Also, for reference, this was the beginnings of my layout for the documentation site.
I’d be interested in helping, to though currently am supposed to be doing some uni work. Hopefully in a few weeks I should have time to contribute though.
I love the idea. I worked a bit on the format of the site tonight. Still very rough draft, but its located at https://jfirwin.com/meshtastic-documentation
I’m still adding the navigation structure on the left and then I’ll worry about beginning to populate it.
Edit: The current home for documentation is at GitHub - meshtastic/Meshtastic. When there’s a live site I’ll try to remember to add the link here so that it there isn’t any confusion about the 404 error on my site.
It’s currently hosted on my Github pages, eventually when it’s more populated, I’ll talk to @geeksville about moving it to the meshtastic organization. Then you won’t have to visit my outdated website.
yep - I’d be totally down for moving them into the meshtastic github whenever you want (and also giving you permissions to facilitate removing old docs as you move them into your new hotness - so we can have one official place)
I suggest we sort out some principles, i.e. who does what (developer, contributor, editor roles, …), what’s the scope of these documents, what remains in the technical repos, a style guide, …
This should not be too heavy, but a little structure to allow us to work together.
Will try to draft something over the weekend for comments etc
Yeah I’d like to focus it to beginners for sure. Point them to the available applications to interface with their new shiny radios and explain what the settings are and what they do.
Beyond that, I want to at least have a “technical” or “developer” section that points to the documentation for each repo. That way we don’t need to document everything in duplicate, but there will be a landing page for everything Meshtastic you’d like to know.
Additionally point to some of GitHubs resources like “how to make a pull request” or things of that nature, so people who have limited experience with git (myself included) can easily make contributions to the project.
Well here we are, nearly a year after this thread and the docs are still a mess. Days wasted.
I spent literally days chasing down a non existent problem due to the docs. Check out the partition docs. Never does it tell you the partition test shown WILL NO LONGER WORK for months!
As a newer user this has me wanting to walk away from meshtastic.
I’d rather help though, as I see this is a great project that at this point seems a bit out of control.
Let me know what I can do.
Roxy
our documentation is pretty scattered and somewhat incomplete. I thought it would be good to put out the following request:
