Hacker News new | past | comments | ask | show | jobs | submit login

In my opinion you are on the right track with the project holding a Documentation folder and the markdown files. Keep it all together or you will have yet another place to maintain.

I would suggest adding the use of Doxygen to your projects. It supports Markdown files as well as Markdown syntax in your code comments. You might find that a lot of what you are documenting in the separate .md files could be a notes or remarks section of your method class comments. This will remove the separation of technical documentation vs. help/FAQ comments by doing all of the documentation in the code. You can then add Doxygen to your build, so that building the project refreshes the documentation. Doxygen can be configured to produce a online html version that can be deployed to an internal web server for quick reference. It can also build .pdf, rich text documents, and unix man pages.

Then if you use Continuous integration/deployment, when you deploy to test, UAT, then eventually production you deploy the official documentation that was generated.

The challenge with all documentation, is, Actually doing it. So it should be part of your SDLC documentation and process. the project/task/request is not done until documentation updated. Make it a checklist item that needs to be reviewed in code reviews. Doing the technical and help/FAQ all in code comments makes that easy.

cheers!




We already have this, the problem is more for processes. Things like "How do I create a build from my commit?". We have dedicated documentation which explains how the build system works in it's entirety as markdown files, but it's painful for a new team member to have to go through that and find out what they need.

A simple Q&A document is failing us as well due to the fact that all commits to our main branches need to go through PR which puts in a high barrier to entry for what might be a minor change. It just discourages collaboration in so many ways.


Maybe the problem can be reframed?

> the problem is more for processes. Things like "How do I create a build from my commit?"

With well set up CI and automated builds, would you need this documentation at all? Could other processes which you currently document also be automated?

In my (limited) experience there's no great way to handle documentation, apart from reducing the need for it as much as possible.

The team I'm on (as a PM, I'm not a programmer) used to use Confluence for almost all technical documentation, apart from the odd Readme file. We use it for product, product range and other team documentation too, which makes choosing sensible top level hierarchy difficult! I don't recommend trying this.

But we finally have decent automated builds in place, and it's made a world of difference. We will soon have decent CI set up too (with Gitlab), at which point lots of project specific technical documentation will move to Gitlab wikis, living alongside the repo it relates to.


> With well set up CI and automated builds, would you need this documentation at all?

We have that. But how would you know that we have that without documentation telling you? How would you know where to find the resulting builds or to check the status?


Fair enough. We currently document such systems details in Confluence, which I can't recommend for all the reasons given by others here.

> We could have the documentation in a separate repository, but if we are going to be making this leap, we want to be sure we are using the right tools for the jobs.

If you haven't considered this yet, it would be very easy to set up a Mkdocs[1] site for testing, using all of your existing documentation. Should be as simple as making a new site and dragging your current docs folder contents into the docs dir. It has good search built in with Lunr[2]. Try the Material theme[3] if looks are important.

[1] http://www.mkdocs.org [2] https://lunrjs.com [3] https://squidfunk.github.io/mkdocs-material/


Why not relax the PR process for the docs directory? If your process is in the way of progress, change the process!


We can't unfortunately. With Github it's all or nothing. We need to enforce code reviews for all merges for certain branches anyway for legal reasons.


So why not have a docs branch open for direct commits, and then merge it into 'certain branches' at meaningful points - release, or whatever?




Join us for AI Startup School this June 16-17 in San Francisco!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: