Evening, y’all. After 8 days of very little sleep, I have seen the promised land and am finally hacking away at my own self-hosted Discourse install. Once I successfully installed my first plugin early this morning I went to work researching and adding every plugin that made sense on the all-the-plugins page.
I run a marketing services company and do a lot of market research so I naturally developed a process to infer the plugins I could trust and that performed well vs. the outliers. A key to the whole process was finding the discussion on meta and digging into the engagement. As time went on I got to be very thankful for plugin developers that included a “See the discussion/Read more about this plugin at https://meta.discourse…” link. If everyone did it, I could have been done in half the time.
Maybe it’s just the former technical writer in me (did a 1-year tour back in Nam … or Austin), but has anyone thought about creating a basic plugin documentation style guide? Beginner’s Guide to Creating Discourse Plugins is fantastic, but it stops at Acceptance Tests. The community clearly values standardization with @eviltrout doing the yeoman’s work in building The Official Discourse Style Guide Plugin, but that only deals with standardizing look and feel.
I contend it would be in the best interest of everyone, especially self-taught developers learning as they go like myself, if there was a style guide to help streamline and standardize the way developers document their plugins. The ultimate responsibility falls back on the developer to follow-through and follow the standards, but from where I sit it’s critical to continuing to grow and scale the platform. At Journalism School, we had the Associated Press Stylebook to follow. Wikipedia has its Manual of Style. Heck, even in the oilfield we have the SPE Style Guide.
I think more than being a burden to force on the community it could be a relief to many. I know I was thrilled when I didn’t have to guess if you spelled it “crosslink” or “cross-link” anymore… it’s crosslink, btw… Discourse’s wouldn’t have to even be all that in-depth. Some suggestions around basic headings to be sure to include would be a wonderful start. I mean, we already do it with the education overlay when you start a new topic… seems like a no-brainer.
Of course, I haven’t slept in a while so these might just be the sleep-deprived ramblings of a lunatic.
Either way, what say ye?
