DEV Community

Discussion on: What is a good documentation for you and what tools do you use?

sunk818 profile image

Do you have an example of this where someone writes separate documentation alongside their code? What purpose would it serve and who is the audience that would need to read it? If a dev is writing for another dev, documentation in the repo works great. If the audience is non-technical, I'd question if that's the best way to communicate documentation. I work at a non-profit and I'm constantly in meetings "translating" between the developer and project sponsor.

Markdown is natively supported in GitHub, so I'd prefer it... but for more complex documents, AsciiDoc looks cool with an online converter like :)

Thread Thread
leoat12 profile image
Leonardo Teteo Author

The documentation would be made along the repository, but it would be available on a website, if any person wanted to read it, that's what I envision. AsciiDoc is also supported by Github and along with Asciidoctor you can convert it to HTML with a great layout and make it available where it is convenient. It would be for mostly techinical people, developers and IT support personel.