Personally, I like using GitLab's Wiki feature. FREE. I tried GitHub Wiki but their wiki only allows you to link images. GitLab wiki actually let's paste images from the clipboard. I don't know about you, but much of my documentation have screenshots.
Publii is static content publisher which you could use as documentation and also makes including images easily. Hooks into GitHub pages (or just export as static set of files).
Other options:
GitBook
WordPress w/ some add-ons (paste image from clipboard)
Confluence by Atlassian
Do you mean imgbb? Again, you have to upload images separately and the workflow is separate. I don't know why GitHub wiki doesn't include image inline attachment like they allow in GitHub issues.
Java Web Developer with a passion for Spring and cloud computing. Know a thing or two about AWS. Trying to learn NodeJS lately with the help of TypeScript.
Confluence is the one we at my company are using right now, but I don't know, I personally thinks that the documentation has to be along with the code to avoid people not updating them. When it is not there in the IDE devs will hardly remember them. I don't.
Code comments is an entirely differently discussion as is readable code. While I agree with your point, I rarely meet devs that like to document. They are called technical writers for a reason and not devs.
Java Web Developer with a passion for Spring and cloud computing. Know a thing or two about AWS. Trying to learn NodeJS lately with the help of TypeScript.
I didn't mean that the docummentation should be comments in code, it would be in the same repository, like markdown or asciidoc files, that would be written while in development and then built along with the code to a convenient format. It is unfortuante because there is no better person to know what they meant by the code than developers.
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 gist.asciidoctor.org/ :)
Java Web Developer with a passion for Spring and cloud computing. Know a thing or two about AWS. Trying to learn NodeJS lately with the help of TypeScript.
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.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Personally, I like using GitLab's Wiki feature. FREE. I tried GitHub Wiki but their wiki only allows you to link images. GitLab wiki actually let's paste images from the clipboard. I don't know about you, but much of my documentation have screenshots.
Publii is static content publisher which you could use as documentation and also makes including images easily. Hooks into GitHub pages (or just export as static set of files).
Other options:
GitBook
WordPress w/ some add-ons (paste image from clipboard)
Confluence by Atlassian
What about imgbb with GitHub wiki?
Do you mean imgbb? Again, you have to upload images separately and the workflow is separate. I don't know why GitHub wiki doesn't include image inline attachment like they allow in GitHub issues.
Confluence is the one we at my company are using right now, but I don't know, I personally thinks that the documentation has to be along with the code to avoid people not updating them. When it is not there in the IDE devs will hardly remember them. I don't.
Code comments is an entirely differently discussion as is readable code. While I agree with your point, I rarely meet devs that like to document. They are called technical writers for a reason and not devs.
I didn't mean that the docummentation should be comments in code, it would be in the same repository, like markdown or asciidoc files, that would be written while in development and then built along with the code to a convenient format. It is unfortuante because there is no better person to know what they meant by the code than developers.
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 gist.asciidoctor.org/ :)
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.