Hi people,
Due to a past post where several users recommended books about programming or more general bibliography (this is the post: https://dev.to/lightalloy/learning-to-love-software-development-books-5e4) I've read past week the book The Pragmatic Programmer.
I have to say, the book is plenty of interesting stuff and thing I will try to implement during this year. The most inmediate and time-gaining measure, I think, is when the book suggests to automate project documentation.
How?
- Use a markup language for the documentation
- Put it on version control software
- Based on the markup language, generate scripts to the required outputs: HTML, PDF, EPUB or whatever you need
I think this is a great concept, and I will work on this in my organization for the next months. And I would like to read from you if you had any experiences with this and recommend tools, etc.
Saludos,
Top comments (12)
I wrote something about this a while back; some of it's GitHub specific but not all. I have since moved the project on to an independent .org as a static site which checks out the project and runs the automated toolkit against it, deployed to hosting with a quick
scp; I like it this way, but that's for a single open source project.Thanks for your feedback. I read your post, went through the documentation of MassiveJS and I think your experience will be useful for what I want to achieve.
Thanks everyone for your answers. By now, I think what I have to do is:
A different flavor of automation for documentation: Keep Your Example Code Green.
Every time you run the tests, you should also run the example code and re-assemble the docs.
Hi Burdette, I'll examine your post. Did a fast reading by now. It covers a good portion of what I have in mind. Thanks for bringing it here!
Nearly all of Microsoft's documentation is fully automated this way.
As I understand it, the documentation is one of the largest repositories hosted on GitHub (it lived there even before the aquisition).
The public can contribute with pull requests and track issues. The documents are all markdown format and a full-automated build process compiles these into the SEO-friendly website. We use the built-in GitHub features to review and comment on submissions and have tags that automate parts of the process like excluding work in progress until it's approved for release. There is also a process to generate other formats like PDF, which is what I did for a free eBook about serverless I hosted on the platform.
You can read the details here if you're interested.
Hi Jeremy,
This is very useful and oriented to what I was looking for. Thank you for bringing it in.
Do you have details about the process to generate other formats?
Saludos,
Also great resources for documentation are the whole Docs As Code / Docs Like Code movement and the WriteTheDocs community 🙂
Hi Horst,
I've been reading this page due to your suggestion:
writethedocs.org
I think this is the approach proposed by the author of The Pragmatic Programmer. Have you experienced some of this on your own practice?
By the way, seems clear that I have to learn intensively markdown language.
In my experience, documentation is as important to the final product as code. Keeping both in sync is much easier when both a stored in the same repository and can therefore also be reviewed with the same tools (pull requests as code review).
Personally, I like working with Markdown for short documents (e.g. READMEs) and Sphinx/RestructuredText or Asciidoc for large documentation bodies like handbooks, guides, references, and so on.
For all of them there’s also strong tooling support available which helps you, for instance, to do automated spell- or link-checking.
I hope this helps and gives you some ideas for your projects 🙂
This indeed helps me a lot. If you don't mind the question, why do you prefer Markdown for short documents? Is there a lack of functionality that makes it unsuitable for large documents?
Saludos,
That’s pretty much it. Markdown itself only supports basic markup like bold, italic and linking, but if you, for instance, want to mark things like keyboard shortcuts, menu entries etc. (which is quite common in manuals and userguides), Asciidoc and Sphinx offer far more.
The technical term for the feature I’m referring to is “semantic markup”. For manuals etc. this is essential.
Markdown, on the other hand, has ether advantage that it is far more common, so onboarding new people is easier.