search

voteflux / flux-docs

Documentation for Flux Parties and the Flux Movement. Covers party setup, social media policies, IBDD and philosophy, internal practices, governance procedures, and all the stuff in between. WIP.
4 stars 7 forks source link

Use of abbreviations #10

Open sventhebarbarian opened 6 years ago

sventhebarbarian commented 6 years ago

In https://docs.flux.party/en/latest/docs/contributing/index.html the term "PR" is used as an acronyms of "pull request" but is not defined so could confuse the lay reader, we could add this in brackets after the first reference to pull requests, or we could make a rule to not use acronyms/abbreviations?

XertroV commented 6 years ago

PR is a super common term and writing it out is a bit tedious. If you click edit on the doc you can add it in parens and when you save it it'll make a pr. Also I put up some images somewhere of this process.

sventhebarbarian commented 6 years ago

Super common for people who work with Git - I am a beginner and needed to re-read the paragraph to click what it referred to, in Slack we have been discussing how to on-ramp people to contribute using the Github structures who have never had experience using repo's etc before.

We should define for all public support systems who the audience is. what its purpose it, it will help us decide what protocols should be in place. If the flux-docs is only a casual info depo for established programmers dropping in common abbreviations is fine, but at the moment the discussion has been to use the flux-docs site as an alternative to a Flux wiki, Paul calls it a point of truth for all Flux documentation and I agree with this ideal.I understand the plan is any interested person can use the generated website to read up about Flux and anyone including non-techys who want to contribute can do so, with documents teaching them how to use Github etc...

XertroV commented 6 years ago

I agree on ramp is important but we shouldn't hide or change language. Maybe adding some of these docs is a good way to skill up yourself and write the on ramps at the same time?

Right place to focus though is on Ppl than can help quickly with skilling up being a longer burn - ie better to have something a few Ppl can contribute to while working on more general stuff.

Right course of actions w small edits is just to make them!

sventhebarbarian commented 6 years ago

I'm getting there.. will start making direct small edits soon :)

Changing one instance of an acronym is a small edit but creating a rule within flux-docs that acronyms cannot be used is a larger consideration.

These comments bring us to questions like who are the target viewers and target contributors which has not been clearly stated yet, the discussion on Slack seemed to strongly lean towards target viewers including uninitiated readers, and the target contributors including people who are not Git literate, the feeling I have from Max is this flux-doc should be directed more towards programmer viewers and contributors only?

@pwhipp @TomSesselmann what are your feelings?

sventhebarbarian commented 6 years ago

I got the feeling from @pwhipp 's comments he is happy to help on-ramp people, and I am too - for myself I would be more interested in taking a teaching and assistance role than making edits myself, we have different ways of contributing, if we can embrace and support all positive activity I think we will get the best results

pwhipp commented 6 years ago

I am happy to help people getting up to speed. There is a glossary and sphinx supports referencing so that you can link to the glossary entry when you first use a glossary term (or every time if you feel inclined). I suggest we use that for any term that might cause confusion.

XertroV commented 6 years ago

These comments bring us to questions like who are the target viewers and target contributors which has not been clearly stated yet, the discussion on Slack seemed to strongly lean towards target viewers including uninitiated readers, and the target contributors including people who are not Git literate, the feeling I have from Max is this flux-doc should be directed more towards programmer viewers and contributors only?

So I hadn't really considered the target viewers / contributors difference yet. It makes sense that'd we'd choose how acceptable acronyms are dependant on where in the docs they are. So having PR on the contribution page is better than having it on the index (though still an argument to be made to keep it even less technical).

I don't mean to imply that flux-docs should only be read by technical ppl - the site is definitely meant for wide consumption of anyone in the party/movement.

if we can embrace and support all positive activity I think we will get the best results

I agree - hope my comments haven't seemed unlike that so far.

There is a glossary and sphinx supports referencing so that you can link to the glossary entry when you first use a glossary term (or every time if you feel inclined)

That's nice - definitely going to be a WIP getting that sort of thing filled out and linked appropriately. And hopefully we don't end up too much like legislation where every second word is hyperlinked to a definition off in some other document :)

sventhebarbarian commented 6 years ago

At the moment it looks like supporter discussion is leaning towards flux-docs being "the" location for information about Flux, replacing the need for any wiki etc..

I think the website voteflux.org could still have a really simple bold outline of information about Flux, but anyone who wants any sort of detail gets pointed to to flux-docs. (I made a note on @TomSesselmann's Trello ticket requesting help updating voteflux's FAQ that maybe the website does not need a FAQ, perhaps it would be better to link people to flux-docs if they are wanting more info - or alternatively have a really simple FAQ on voteflux with each entry pointing to more detailed explanations on flux-docs..)

If this is the structure we want then the intended audience for flux-docs is everyone, we would need to assume people landing on flux-docs have no prior knowledge about Flux, Git, programming, blockchain, philosophies, etc.. This does not mean we cannot have technical info there, it just means we need a forgiving structure and wording, and lots of reference links for clarifications.

XertroV commented 6 years ago

replacing the need for any wiki etc..

Yeah, we can still have a wiki but would be for more general or less canonical info. Also it's still fairly similar to a wiki, anyone can make a PR, etc.

I think the website voteflux.org could still have a really simple bold outline of information about Flux, but anyone who wants any sort of detail gets pointed to to flux-docs

This sounds like a good plan

maybe the website does not need a FAQ, perhaps it would be better to link people to flux-docs

Yup, I started on a membership guide for that reason.

If this is the structure we want then the intended audience for flux-docs is everyone, we would need to assume people landing on flux-docs have no prior knowledge about Flux, Git, programming, blockchain, philosophies, etc..

The problem with presuming ppl know nothing is that it means you take on a lot of responsibility for educating them. In the long run that is doable but focusing too early on that is a mistake IMO, better to presume an ability to research what they need to and that they have a beginner level knowledge.

Reference links are a good way to start (e.g. a link at the top of a page like "Don't know what blockchain is? Click here!")