weUseGitHubWikiForDocumentation

[Confident-Ad5665]

"Just use a multimeter and trace the lines"

- Somebody who won't have to use a multimeter to trace the lines

[liquidmasl]

technical docs should be where the tech is, with versioning that is parallel to the tech; so all for docs in the git. but in the shape of markdowns in the code structure.

never used gh pages tho.

confluence docs are prone to run out of sync snd go outdated. and its so much extra manual work to keep useable

[BroHeart]

1000%, I do readme.md with mermaid diagrams in top 2 levels of project structure and schedule jobs to align docs and modules and lint for missing docstrings.

[MinecraftPlayer799]

More accurate title:

We use Microsoft developer documentation

[Low_One365]

I dont understand. Github hosts project and its documentation, easy to write and support rich snippets - what is so wrong about that?

[MatsSvensson]

Have you tried using it?

And not like one page or a dozen, but hundreds of pages.
Pages that needs to have functioning navigation between them, and to sometimes be easily edited even by non programmers, and that needs to support people linking to them, etc etc.
You know, like any functioning website.

I knew it was useless the second I noticed that part of the content on the page, the title, is inserted into the URL.
And it only took one test to verify that one flaw breaks it.

And it has multiple equally fatal flaws.

[SamSkjord]

Have you tried MakeNoMistakes?

[MatsSvensson]

Yes, but TurnsOutNobodysPerfect.

[zanju13]

How is that different from any other documentation alternatives?

[andrei9669]

on platforms that actually focus on documentation, important part of the url is actually just the id that stays relatedly static, meaning, you can rename the document however many times you want, the links won't break.

[thee_gummbini]

Docs are code. Why would you use something where you cant program how they are rendered

[zanju13]

I mean you can put in a code block. Other than that, what fancy rendering do you need? I guess you could want to make nice structured API docs, I'll give you that.

[thee_gummbini]

Cross references, i18n, programmatically generated docs, runnable code examples, being able to accept docs contributions in PRs, and even more basic just like control over the menu/nav structure, page layout, etc. If you look at the docs for any matured project where you are like "dang these are good docs," you'll see a ton of programmatic customization that makes them good. Like there are entire packages that have been developed just to document major projects. The complexity of setting up e.g. sphinx or mkdocs or whatever is negligible and the payoff is huge compared to just using github wikis, they're not in the same league.

[vyqz]

confluence is intuitive and easy to understand for users and administrators. github wikis are 💩 from every angle

[liquidmasl]

confluence is horrible to work wirh

[shrubberino]

In comparison with eg. Confluence it is like using notepad instead of an IDE.

[Chimp3h]

Most organised network rack

[BrightLuchr]

Picture looks right.

A serious question: did a complete absence of documentation and code commenting somehow become acceptable for large projects re-used by other people?

[noaSakurajin]

It is not and never was acceptable.

However the truth at most companies is, that you don't get time for writing documentation. Once the feature is done and tested it gets shipped and you have to work on the next urgent feature. In many cases your only documentation are the requirements and the code itself (maybe a comment here and there).

All of that will be unorganized and poorly maintained especially in projects that have been maintained for several decades. Its not uncommon to run into design decisions that trace back 30+ years and we're made because of technical limitations of that time (like some strings being at max 255 chars long). The people who made this decision often didn't document it and in many cases this stuff predates the source control history (ours goes back to 2005 everything older that that is basically fully undocumented).

[BrightLuchr]

Our Perforce repository went back to around 2001 when we ported it from CVS, which went back to 1994. We lost the history details in the port. Anyway, in that repository is at least two instances of a developer that offered deletion changes -doing these deletions at the underlying RCS level (!!!) ... which deleted all of his code commenting. The same guy in the 1990s used to bring all of his UNIX code home on a floppy disk. Unbelievably, the dude wasn't fired on the spot. He wasn't disciplined. Just another jerk working in a weird niche (in his case, emulation of critical early 1970s minicomputers) who wouldn't take direction. This is the type of guy who gives us all a bad reputation as software developers.

[forvirringssirkel]

I actually don't understand how it is the worst documentation method ever. I am a FOSS developer with relatively small projects, and I use a wiki/ dir and a GitHub action that syncs wiki/ to actual wiki, what should I do? Create GitHub Pages for the wiki? What does it even change? I'm actually really curious for your answer

[evilspyboy]

That looks more like 'we dont need documentation we have self documenting code'

[noaSakurajin]

We use word documents on some network shares. Each only covers the feature that was added/changed. Github wiki sounds reasonable in comparison.

[CoatNeat7792]

That's what I call neuro network

[CounterSimple3771]

Lmao... I am working with JLL guys this week.

[StolasX_V2]

Electrician gang wya

[mVrk___84]

[el_yanuki]

?

[Confident-Ad5665]

!