Restructuring of the site

[ronaldtse]

We want to restructure the site so we can address concerns of different audiences.

1. Authors that use metanorma software. They need documentation on authoring, setup. For each flavor, we need to provide flavor specific guidance.

2. SDOs who want to adopt metanorma, customize metanorma. They need to know the benefits of metanorma, the software components, how to setup, any best practices. What can be customized: XML schema, layout design. Software and infrastructure setup like the metanorma registry.

3. We should provide a page that describes consulting/tailoring of metanorma to the adopting organizations. We should have a pro-bono program that they can apply for, and we need to list out eligibility criteria (eg international organization), what we require, and the organizations that we have helped.

4. There should be a user committee that drives metanorma development and can take their feedback.

[strogonoff]

@ronaldtse I feel like there’s a misunderstanding since this restructuring is already partially done with author’s and builder’s documentation split and flavour documentation separated, I’m not confident in working on this issue without a discussion over a call to get a better idea

[ronaldtse]

This is just a high level overview of what the current goals are.

The current site structure addresses some but not all of audience separation, e.g. the site header describes "authoring docs", "flavors", "specifications" and "blog". It doesn't help much with the SDO who wants to adopt metanorma -- we need a statement of benefits with it too.

In particular, for example for CSD (https://www.metanorma.com/author/csd/). The quick start should just be the Guide (https://www.metanorma.com/author/csd/authoring). And the Guide on the site is incomplete...

There's lots to be done but it has already gotten better. One step at a time.

[strogonoff]

@ronaldtse

The quick start should just be the Guide

IMO this would be a big mistake, since a new author would have zero background on Metanorma, its installation, authoring methods etc.

The way it’s planned currently, there are two parts to the docs:

• A set of tutorials for people who are just coming in, describing creation from scratch. (Sending people off to a sample would not suffice.) Ideally there should be a quick-start tutorial for Metanorma generically, and for each particular flavour. This would be 95% useless to someone who already went through the process, but invaluable for new users.
• Topic & reference guides, for people who are already familiar with how it works and need to find in-depth information about specific aspects, such as document attribute behavior, particular building caveats, and so on. Significant part of that would be irrelevant to newcomers, but super essential to someone using Metanorma not just to play but seriously.

A brief landing page for the flavour (e.g. https://www.metanorma.com/author/csd/; there’s a so-called “quick-start” there but that section may be renamed) must allow respective target audience to get to what’s relevant to them with as little mental overhead as possible. (I’d take an intuitive quick extra click over mental overhead.) It should as well provide handy links to Metanorma and AsciiDoc basics.

And the Guide on the site is incomplete

Flavour-specific authoring documentation in current initial stage was compiled from what was available in respective gem READMEs, so yeah not yet complete but I’m working on it.

Being a reference rather than a tutorial, it doesn’t duplicate generic Metanorma attribute/markup reference by design. (On the other hand, upcoming flavour tutorials should be mostly self-containing as possible as far as the basics go, and they can duplicate some of the info in both generic & flavour-specific references, possibly including the most universal & simple installation method in the first tutorial.)

It doesn't help much with the SDO who wants to adopt metanorma -- we need a statement of benefits with it too.

As far as practical aspects for SDOs, I see this as part of builder’s documentation (https://www.metanorma.com/builder/). There should be tutorials & references aimed at organizations (that’s on my plate I think, primarily).

Two issues I see right now

• As far as statement of benefits, I lack information to write that up.
• I am not sure we are aligned on principle. I’ve invested some thought into structuring the documentation, perhaps I should share more with you about this approach and we should discuss it out. Right now I feel like we’re not on the same page and may be talking past each other a bit

[opoudjis]

I've also been asked to help out with the documentation; and as you can well imagine, I have no desire to keep rewriting the documentation I've already written.

I likely have a third opinion about what the documentation will look like, but I have to say, I'm liking the structure Anton put up a lot, and I think we should continue with it. Detailed comments:

(1) there needs to be a gentler, example-based introduction to how to write Metanorma Asciidoctor (which I have in fact written: it's the https://github.com/riboseinc/metanorma-iso/blob/master/docs/asciiiso-syntax.adoc, and it needs to go in under WritingAsciidoc;

(2) The how-to material I wrote in the blogs for authoring and doc conversion also need to go under WritingAsciidoc, as a tutorial; but they can be slotted in as just links, they don't even need to be copy-pasted across.

(3) the material provided under Document Format and Document Attributes is already obsolete and incomplete, because I am continuously adding to it; but now that I know it's been broken up and distributed there, I can fill it in, and make the metanorma.com instance rather than the READMEs the source of truth;

(4) the Flavours documentation is as I had it --- additions to the base, rather than integrated into the base; but frankly, I think that's much less fragile than the alternative you had in mind, of includes-based rewriting of the base documentation. That can nonetheless be explored. I guess. Anton spoke of the tutorials structure; I think the Reference can continue as it has been in the READMEs and what is now there in the flavours, as a "what's specific to this flavour" listing of features, whereas the tutorial will be perhaps an includes-based rewrite of the Quickstart document, adding in flavour-specific aspects.

(5) The Metanorma-Builder documentation is hidden from the front page, and needs to feature more prominently ("For Developers").

[opoudjis]

Incidentally, Ronald,

We should provide a page that describes consulting/tailoring of metanorma to the adopting organizations. We should have a pro-bono program that they can apply for, and we need to list out eligibility criteria (eg international organization), what we require, and the organizations that we have helped.

There should be a user committee that drives metanorma development and can take their feedback.

We are simply not resourced now to deal with these. Come back to these in six months. You are spreading your existing resources too thin by committing to these, and you should be consolidating Metanorma with its existing users (and getting more resources).

Oh, and do not even consider getting a user committee (let alone a Metanorma customisation consultancy!) unless you have a project manager on board to manage and prioritise what may become a deluge of requests. You are not that project manager, Ronald, and neither am I. :-)

[opoudjis]

I am reviewing tech documentation in https://github.com/metanorma/metanorma.com/issues/72.

[sgilsonator]

I've proposed to @ronaldtse that the docs be organized around activities rather than roles. So for example, "Authoring" and "Building" instead of "Authors" and "Builders." @opoudjis, how does this sit with you?

[ronaldtse]

Agree with @doktorgee 😉

[opoudjis]

@doktorgee In general: I care about the content, I do not care at all about the organisation of the content (apart from ensuring that I don't have to author the same content twice). That was always between @strogonoff and @ronaldtse. So indifferent to activities vs roles.

[strogonoff]

Hi @doktorgee!

“Building documentation” is already a subject in Metanorma’s docs, and it means a different thing. When referring to builder’s docs we’d either have to disambiguate always, or reconsider the wording we use for the activity of taking the source and outputting end deliverables (there were reasons to choose “build” over “generate” and “convert” for that process).

Generally using verbal nouns together with “documentation” causes ambiguity. (Consider: “Amending documentation”, which could be about how to amend something, or how to amend documentation itself. In this case one would choose “amendment”, but we don’t have this luxury with “authoring” and “building”.) This is especially delicate with Metanorma due to it being so meta wrt. standards and documentation.

We can play with the phrasing to avoid those pitfalls, but so that we aren’t renaming things for the sake of it could you please step back and give some detail on what problem we’re trying to solve here?

NB: I’m not sure why this issue is open since the restructuring has been completed recently. Establishing a committee and a pro-bono program sounds outside of site restructuring.

[sgilsonator]

Anton, thanks for your reply. The reason I'm interested in organizing around actions rather than roles is that I think users will be more likely to identify with a task than a role. A lot of tech doc teams have to build and maintain toolchains, manage workflows, create graphic elements, query and report data, deploy tools and standards, and so on. Teams need to be self-sufficient so that they aren't relying on IT or Operations groups to support them. A typical tech writer does a lot more than write techdoc -- they need to be flexible and adaptable. So their titles (roles) don't sufficiently reflect what they actually do to help their teams. My concern is that someone might not identify all that well with what we're calling a "Builder" even if they routinely do what we would call "building."

This relates to people visiting metanorma.com to evaluate the tools as well as anyone visiting to refer to the docs in order to get something done.

I've sent a separate note asking for guidance on the workflow for creating and approving plans. I'm looking forward to everyone's response. Thanks.

-Stephen

On Mon, Apr 8, 2019 at 2:14 AM Anton Strogonoff notifications@github.com wrote:

Hi @doktorgee https://github.com/doktorgee!

“Building documentation” is already a subject in Metanorma’s docs, and it means a different thing. When referring to builder’s docs we’d either have to disambiguate always, or reconsider the wording we use for the activity of taking the source and outputting end deliverables (there were reasons to choose “build” over “generate” and “convert” for that process).

Generally using verbal nouns together with “documentation” causes ambiguity. (Consider: “Amending documentation”, which could be about how to amend something, or how to amend documentation itself. In this case one would choose “amendment”, but we don’t have this luxury with “authoring” and “building”.)

We can play with the phrasing to avoid those pitfalls, but so that we aren’t renaming things for the sake of it could you please step back and give some detail on what problem we’re trying to solve here?

NB: I’m not sure why this issue is open since the restructuring has been completed recently. Establishing a committee and a pro-bono program sounds outside of site restructuring.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/metanorma/metanorma.com/issues/65#issuecomment-480697530, or mute the thread https://github.com/notifications/unsubscribe-auth/AEnPvekfS3-YC0CCiLRfT-2YVP9Aivqcks5vet5ZgaJpZM4bWF-F .

-- Stephen Gilson Strategist and Content Manager