Gregory's Server#TechWriters matter
Discord is NOT documentation
masukomi
35 comments
Morgan `indrora` Gangwere
genofire
@masukomi discord is so annoying - even for chat / i prefer @matrix . but yes documentation should happen per webseite generator like:
Ariel C.G.
genofire
@arielcg @masukomi the static-side are markdown or asciidoc inside of your git-project. I do not like Github Wiki (or gitlab), that creates a new versioning (commit ids) ... inside the existing git-project the code is equal to documentation (and easy to find with git-tags) ... this git-tag could auto detect by some static-site generator: 
Natasha Nox 🇺🇦🇵🇸
@masukomi documentation on Discord equals no documentation at all. Anyone who does this should be utterly ashamed of themselves and shamed by the community as a whole. By now a tool that fetches anything from a Discord and translates it to markdown text (either doc-like or chat-like, perhaps channel-wise for better readability) would be kinda useful for preservation purposes.
Paul the Nerd
@masukomi It is also not an issue tracker "To report issues, join our Discord" annoys me no end 
Rachel
@masukomi@connectified.com I have yet to encounter projects with docs exclusively on discord
SarahGreyWolf
@masukomi not documentation, not support, not an issues manager, not a file host and not a replacement for forums  
masukomi
@sigi714 🤔i guess it depends on what you’re documenting and how well you’ve accommodated blind people. It sounds like a silly alternative but i can think of a bunch of open source project that would dramatically benefit from having a video overview and a usage guide video. It’d be terrible if it was the only form of documenting functions but i’d watch a video demonstrating how to use an APIs primary functionality
masukomi
@sigi714 yeah, the problem is that different people learn different ways. In your particular case I'd note 3 things: 1. that YouTube transcribes everything. 2. those transcriptions are easily attainable Easiest way i know to get a transcript from YouTube is to just go here https://tactiq.io/tools/youtube-transcript but they're not doing anything fancy. it's easily available to all. I'd also note that Whisper is exceptionally good and can transcribe _any_ audio (podcasts) for you.
masukomi
I think your comment is a good example of why there's value to multiple forms of documentation. Also, to how OS people who DO make videos could really help things with little effort, by making the transcripts of them easily available on their sites.
hacknorris
@masukomi but is it good to have discord ADDITIONALLY to wiki section in repository?
masukomi
@hacknorris well a) essentially no-one ever populates wikis in a meaningful manner so they rarely count, which means no… because it’s functionally the “discord is docs” answer
hacknorris
@masukomi like if i'd do a thing like discord.py did (i know it's discord-related, yep? just as an example, splitting wiki from chat i meant). all their docs are well documented and you can base only off that but if you'd like further help or for example ask for specific parts of code (maybe in order to make a fork?) you can go into their discord...
masukomi
@hacknorris oh sure, a human who was actually involved in the creation, that you can ask questions of is a great form of additional support. BUT it's probably not as good as you think. There is a _huge_ difference between a person who can make a thing well, and a person who can _explain_ a thing well. The most common example of this is programming experts who have completely forgotten what it was like to be a newb, & don't understand how much of their understanding they're taking for granted. 
james is afk
😡 Code should not be in the hands of private for-profit companies 
masukomi
@mpldr that may work for you, but overall i’m a Hard Disagree 1. Most apps aren’t for the command line. Thus manpages are irrelevant
Moritz Poldrack :arch:
@masukomi I semi-agree there. Of course writing a manpage for an image upscaler that does not have a command line interface would be silly, but for documenting config formats and switches I've found them incredibly valuable. Apart from being easy to search, they can be significantly more thorough than a –help text ever could and having them available offline certainly has its advantages for things like DNS resolvers. For examples, a markdown wiki (of whatever shape) can be a useful resource.
Moritz Poldrack :arch:
@masukomi and bad documentation comes in all flavours, unfortunately. I even have a list in my bookmarks, I call "documentation hell" and manpages are a rare occurrence on that list. Whether I would agree with the first statement I am not sure either. Many programs come with switches that alter the programs behaviour (think proxies in chromium). Calling them irrelevant is ignoring the reality that is daemons and other non-interactive programs. |
@masukomi discord-as-docs brought to you by the people who came up with ask-if-you-have-questions job onboarding 🥴