Follow

I really want the Mastodon documentation to have a good structure rather than just all information thrown together in a pile. I'm not sure how though.

@Gargron for the API stuff, I'd suggest documenting it in some machine-readable format and then generating the human-readable docs from that

@Gargron that would give you the added bonus of having the documentation double as a test suite for itself

@ben @Gargron I like the format and display of Swagger.io -- many inline documentation generators do something similar.

There's also PostMan

@Gargron Have you reached out to anyone who knows content strategy? Seems to me like this is a great place to ask for help

@schlink I'm not asking for a tool. I said I don't know how to hierarchically structure the information

@Gargron @schlink Split it into different audiences: end users, admins, translators, devs/hackers,

@Mainebot Don't you have a full-time job though? This is probably a one-time large gig though since the software's functions don't change that often. If you want to go at it be my guest.

@gargron look if the gig pays, I can recommend someone.

terrible pun 

@Gargron i'd be willing to take a stab at it, having just cleaned up a lot of docs for pixelfed. it's still incomplete but it's much less messy than it used to be. i would need to sit down and try to map it out with you first, though.

@Gargron Try consulting writethedocs community

Here's a general guide on approaches of how to write documentation -- writethedocs.org/guide/

You should also ask specific questions on community slack channel -- writethedocs.org/slack/

@Gargron Mastodon is better than Twitter you should make mastodon a single social network this would mean the end of Twitter and Square!

@peppone What do you mean by a single social network? Like, for singles?

@Gargron Thank you for the reply! Anyways What I mean is that the first time I knowed about mastodon I thought it was a social network like Facebook, Instagram and Twitter and not Open Source and decentralized. I know your goal is another but given the quality of the social network I thought you could make it to one server and not with other instance

@Gargron
i suggest you have a good look at the archwiki :) in my opinion and in many others they did a particularly good job that documenting .
now i don't suggest you copy and paste their scheme but it would be good inspiration i suspect.
do be the best got to learn from the best right.

@Gargron check this out:
divio.com/blog/documentation/

It blew my mind when I first read it. Now I try to follow it with my own documentation writing.

@Gargron I'm a professional tech writer… New to Mastodon though, so, err, send me a PM or something?

@Gargron And I freelance and have experience with documenting distributed tech :)

@Gargron
The wiki formats of Wikipedia and the Arch Linux Wiki are excellent models of easily-accessible, well-organized information. An additional dictionary of special terms (e.g. "toot"...) would be welcome.

@Gargron

Hey there, I've dabbled in writing documentation for projects of varying technical-ness and I wanna say:

It's really unlikely another project's structure is going to be a perfect fit for you; the organization of the component sentences and paragraphs into their documents and such is one of the hardest parts of it for me and varies more by project than anything else.

tl;dr: there's no sure way to do it, and it's damn tricky to find even an acceptable way.

Sign in to participate in the conversation
Mastodon

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!