Wiki cleanup

Hi Kenneth

I've started to revise and organize parts of the documentation wiki,
starting with things I think will be uncontroversial. I figure that this is
a good thing to do while I'm new, since it's obvious to me what is
confusing or hard to find, but do speak up if I get carried away.

great, thanks for your work :slight_smile:

Two major problems that stick out to me:
1. There is a large but incomplete duplication of content between the TDF
wiki, the documentation website, and the main website. I think there needs
to be a discussion about what should go where.
2. There seems to be two very different kinds of content on the TDF
documentation team sub-wiki: pages for users, and pages for the
documentation team. On the other hand, there is also miscellaneous info for
users scattered around other parts of the wiki.

Could you add links to what you're talking about and the duplication you
see, it would be easier to help you.

Currently it doesn't look like it would be trivial to move the all the
users-facing wiki pages to the documentation website, so perhaps as a
temporary solution we could make a separate section or subsection on the
wiki to collect everything together. I'll think about what to name this
hypothetical section and wait for other opinions before I do anything.

You can open a discussion page under the documentation project in the
wiki and put the links of the page you want us to discuss, that would be
really helpful
Cheers
Sophie

sophi wrote

Could you add links to what you're talking about and the duplication you
see, it would be easier to help you.

Right. So on the main website doc page
(http://www.libreoffice.org/get-help/documentation) we have: getting started
5.2, installing extensions, user guides for 5.x and 4.x (ODF, PDF,
purchase). Other help resources on separate pages.

On the documentation website
(http://documentation.libreoffice.org/en/english-documentation/), then, we
have: online help, quick reference, getting started, individual app guides,
and "more" (which is currently empty). Getting started and user guides,
then, have ODF, PDF, purchase, *plus* ODF/PDF individual chapters and an
online version.

The wiki Publications page
(https://wiki.documentfoundation.org/Documentation/Publications) has links
to nearly everything, including things not on the others. I've already moved
the least "publication"-like things to another wiki page.

I don't know who's in charge of the websites or what the plans are, but the
current situation is a mess...which I'm happy to help clean up if it's
something anyone can do.

Aside: design-wise the doc website also seems rather questionable to me, and
hard to navigate. Giant text, giant graphical tiles for links, giant inline
pictures, collapsing content instead of sidebar nav. But that's a topic for
another time.

You can open a discussion page under the documentation project in the
wiki and put the links of the page you want us to discuss, that would be
really helpful

Sure. Actually, I've seen some statements about the wiki needing cleanup
overall, so I'd be interested to hear from whoever has thoughts about that.

--Kenneth

Talk page is started:
https://wiki.documentfoundation.org/Talk:Documentation

Though now that I've done this, I remember how much I dislike wiki-style
talk pages compared to actual threaded conversations. Anyway, take a look.

--Kenneth

Progress report on what I did last week.

1. Moved miscellaneous links, mainly wiki pages, which neither seem like
"publications" or "third party" resources, to a new Other Resources page.
Renamed old "Other Documentation and Resources" to "Third party resources.
Updated links and descriptions everywhere I could find them to make this
organization transparent.

Name "Other Resources" is not ideal, but this can be improved once
reverything is more or less organized. For example, separate pages (or page
trees) for tutorials, installation instructions, and so on.

2. Massive overhaul of Doc Team top page. Started by simplifying to two
columns and fewer sections, followed by several successive rounds of
revision and simplification. I think the result is much more
understandable, but again could use another round after everything else is
organized.

3. Rewrote Users page, with updated links pointing to current main website
when possible.

4. Updated the Documentation menubar.

5. Miscellaneous fixes to page titles, categories, links, and content.

--Kenneth

Progress report for July 31.

1. Moved doc team pages, in particular about the help system, under
Documentation. Left user doc pages alone.
2. Updated Documentation/Development intro page.
3. Moved and retitled many pages, updated TOC again.

Let me know if I screwed anything up so far.

New issue: there are two help content authoring pages with very similar
structure, but completely different content. One was originally a subpage
of Documentation (current Documentation/Help) and the other was a top level
page (current Documentation/Help_Content). Someone who knows this stuff
well should combine them. Or, if they were meant to serve different
purposes, resplit the info properly.

Hi Kenneth

sophi wrote

Could you add links to what you're talking about and the duplication you
see, it would be easier to help you.

Right. So on the main website doc page
(http://www.libreoffice.org/get-help/documentation) we have: getting started
5.2, installing extensions, user guides for 5.x and 4.x (ODF, PDF,
purchase). Other help resources on separate pages.

Yes

On the documentation website
(http://documentation.libreoffice.org/en/english-documentation/), then, we
have: online help, quick reference, getting started, individual app guides,
and "more" (which is currently empty). Getting started and user guides,
then, have ODF, PDF, purchase, *plus* ODF/PDF individual chapters and an
online version.

This site as originally designed to be a text-free, quick way to
download published LibreOffice literature from the community, that
otherwise was diluted in the wiki and many other pages. The page layouts
there are responsibility of the national communities, the current layout
is just a suggestion. Contents is responsibility of the communities too,
and are in general, the translation of the English guides.

The website is also accessed by the software in the Help menu "User guides".

There are about an average 600 visits a day in this site and these are
the figures of downloads in the last week:
Quick reference card (ODT): 216
Calc guide (PDF): 122
Base guide (PDF): 100
Writer guide (PDF): 79
(...)
Getting Started Guide: 67

There is almost no download for ODT files or chapters.

Given the above, we can consider to work on
- Remove all ODT files (and archive them in the wiki or ODFAuthor)
- Remove old books and make the page simpler
- Improve visual appearance of the page
- Stimulate national communities to add contents to the website
- more...

The wiki Publications page
(https://wiki.documentfoundation.org/Documentation/Publications) has links
to nearly everything, including things not on the others. I've already moved
the least "publication"-like things to another wiki page.

I don't know who's in charge of the websites or what the plans are, but the
current situation is a mess...which I'm happy to help clean up if it's
something anyone can do.

Thanks for the initiative, much appreciated. No one is actually "in
charge", pages are created by the community members so everybody is "in
charge", including removing SPAM and caring on the accuracy of the
information. That is the way TDF wiki works.

Aside: design-wise the doc website also seems rather questionable to me, and
hard to navigate. Giant text, giant graphical tiles for links, giant inline
pictures, collapsing content instead of sidebar nav. But that's a topic for
another time.

Please feel free to suggest another layout/color/design. As said above,
it was conceived to be a download point for published community
documents, and not a documentation (contents) website per-se.

You can open a discussion page under the documentation project in the
wiki and put the links of the page you want us to discuss, that would be
really helpful

Sure. Actually, I've seen some statements about the wiki needing cleanup
overall, so I'd be interested to hear from whoever has thoughts about that.

Thanks again for raising the issue.

Hi Kenneth

I reviewed the doc entry page and removed some obsolete pages and their
associated links.

Thank you for your help here.

Kind regards

Olivier,

Thanks for trying to explain this to me. I'm not certain I understand, so
I'll try to confirm.

It sounds like there isn't a concrete plan for the content of the
documentation website, which is why it mostly duplicates the download
options on the main website and wiki right now.

But it sounds like the documentation website is intended to be the primary
source for guide downloads and similar documents. In this case, I think the
next step is to remove the download links from the main website's
"documentation" page, and replace them with links to the documentation
website, help website, and wiki.

Then we can work on the publication website. Again, I'm happy to help with
this, but how do we edit it? The wiki page https://wiki.
documentfoundation.org/Documentation/Guides_Website is incomplete.

As for the wiki, my guess is that in the short term we should leave it
alone, since this page does make it very easy to find everything while the
other websites are in flux.

Moving onwards...

I don't know who's in charge of the websites or what the plans are, but
the
> current situation is a mess...which I'm happy to help clean up if it's
> something anyone can do.

Thanks for the initiative, much appreciated. No one is actually "in
charge", pages are created by the community members so everybody is "in
charge", including removing SPAM and caring on the accuracy of the
information. That is the way TDF wiki works.

I think I understand what you mean by this from reading the the thread
"simplifying documentation". Okay, so no one holds any formal
responsibility. I didn't mean to imply that. (For me at least, the meaning
of "in charge" is loose enough to include temporary volunteers.) What I
want to know is who is working on the website, which does not seem to have
open editing. Based on that other thread, it seems that this would be the
"infrastructure" team. Is this correct?

Aside: design-wise the doc website also seems rather questionable to me,
and
> hard to navigate. Giant text, giant graphical tiles for links, giant
inline
> pictures, collapsing content instead of sidebar nav. But that's a topic
for
> another time.

Please feel free to suggest another layout/color/design. As said above,
it was conceived to be a download point for published community
documents, and not a documentation (contents) website per-se.

I have an idea in my head, but it will take some time to spell it out, so
I'll do that in a new thread when I get a chance.

--Kenneth

Hi Kenneth

Olivier,

Thanks for trying to explain this to me. I'm not certain I understand,
so I'll try to confirm.

It sounds like there isn't a concrete plan for the content of the
documentation website, which is why it mostly duplicates the download
options on the main website and wiki right now.

The plan is to have a focal point for download of community
documentation products, in order to increase the visibility and
effectiveness of the work done by documentation volunteers while
supporting users with the right information. By having ease access to
documentation web page we also expect to spark interest of the community
at large to contribute to documentation and be part of a community.

The community is multilingual, multinational and driven by volunteers.
Not every national LibreOffice website follows the contents, internal
URLs and organization of the English website, which turns the
documentation URL in these sites hard to follow.

But it sounds like the documentation website is intended to be the
primary source for guide downloads and similar documents.

yes.

In this case,

I think the next step is to remove the download links from the main
website's "documentation" page, and replace them with links to the
documentation website, help website, and wiki.

Yes, and it depends on the national communities decision to make it.
Some communities made it happen, others didn't. Some communities are
very active, others are dormant.

Then we can work on the publication website. Again, I'm happy to help
with this, but how do we edit it? The wiki page
https://wiki.documentfoundation.org/Documentation/Guides_Website
<https://wiki.documentfoundation.org/Documentation/Guides_Website> is
incomplete.

My fault. I'll amend the doc wiki page on this. Please follow
instructions of https://wiki.documentfoundation.org/Website . Poke me
when you get a login.

As for the wiki, my guess is that in the short term we should leave it
alone, since this page does make it very easy to find everything while
the other websites are in flux.

Moving onwards...

    > I don't know who's in charge of the websites or what the plans are, but the
    > current situation is a mess...which I'm happy to help clean up if it's
    > something anyone can do.

    Thanks for the initiative, much appreciated. No one is actually "in
    charge", pages are created by the community members so everybody is "in
    charge", including removing SPAM and caring on the accuracy of the
    information. That is the way TDF wiki works.

I think I understand what you mean by this from reading the the thread
"simplifying documentation". Okay, so no one holds any formal
responsibility. I didn't mean to imply that. (For me at least, the
meaning of "in charge" is loose enough to include temporary volunteers.)

yes

What I want to know is who is working on the website, which does not
seem to have open editing. Based on that other thread, it seems that
this would be the "infrastructure" team. Is this correct?

Almost, the infrastructure team supports the service but does not deal
with the contents (well sort of, it must be related to LibreOffice). The
list of national communities names is here:

https://wiki.documentfoundation.org/Website/Web_Sites_services#International_Sites

    > Aside: design-wise the doc website also seems rather questionable to me, and
    > hard to navigate. Giant text, giant graphical tiles for links, giant inline
    > pictures, collapsing content instead of sidebar nav. But that's a topic for
    > another time.

    Please feel free to suggest another layout/color/design. As said above,
    it was conceived to be a download point for published community
    documents, and not a documentation (contents) website per-se.

I have an idea in my head, but it will take some time to spell it out,
so I'll do that in a new thread when I get a chance.

You are most welcome to show your ideas. Really.

Kind regards and a big thanks.

Update: I've rewritten Documentation/Development, integrating the contents
of Documentation/Easy_Hacks (most of which wasn't, in fact, easy hacks) and
splitting the detailed guides instructions and wish list off into new pages.

I also edited the guides instructions a bit, but I haven't touched the wish
list yet. Some further refinements might be in order once I address the
latter.

I've added some todos to
https://wiki.documentfoundation.org/Talk:Documentation, if anyone else
would like to help. This is in addition to my previously written notes
about the organization of user pages and doc team pages.

--Kenneth

While your interest in the documentation wiki is appreciated, have you
considered seeking the consensus of other documentation contributors
before making these changes?

Dave

Well, my assumption has been that these changes shouldn't be controversial,
but can be reverted if necessary, or corrected by others that know better.

Perhaps it would be better to propose changes in advance, just in case. At
the same time, I'm under a time crunch to finish this during summer
vacation while I have the time and attention to wrap my head around all of
it...

Anyway, consider today's additions to the talk page my proposal for how to
proceed from here.

--Kenneth

One more thought. I have sort of been hoping for more input that I've got
until now. There hasn't been any comment on the issue of user docs / doc
team pages, as well as several later queries. My progress reports are also
an implicit call for feedback. So I'll make it explicit: Any ideas?

--Kenneth

Hi Ken

One more thought. I have sort of been hoping for more input that I've got
until now. There hasn't been any comment on the issue of user docs / doc
team pages, as well as several later queries. My progress reports are also
an implicit call for feedback. So I'll make it explicit: Any ideas?

I went thru the changes and I don't have any objections.

Thank you for the cleanup.

Kind regards
Olivier

This was a task that sorely needed doing.
Furthermore, it is easier to make the desired changes, and revert/modify
later, than try to gain some type of consensus, prior to doing them.

jonathon

While your interest in the documentation wiki is appreciated, have you

This was a task that sorely needed doing.

True that the documentation section of the wiki was/is in need of some
attention, no more than other sections and in most instances Kenneth's
changes have IMO been worthwhile improvements.

Furthermore, it is easier to make the desired changes, and revert/modify
later, than try to gain some type of consensus, prior to doing them.

The JDI policy may not always the best approach and reversions take more
time than a simple notification. Maybe your interpretation of the term
"consensus" is different to mine. In this context it would be sufficient
to post a notification of the intended changes to this list and if no
objections/alternatives are put forward within a reasonable period of
time, then go ahead. This approach would have avoided the situation with
the FR FAQ being moved on the wiki, since Sophie could have pointed out
the potential problem Kenneth had not foreseen and saved additional
unnecessary work.

jonathon

Regards
Dave

Hello all.

I'm continuing to work a bit on the wiki, now focusing on organizing user
docs. For a refresher, see what I wrote in August:
https://wiki.documentfoundation.org/User:Khanson679/Wiki_cleanup

I haven't gotten much input on this issue, but I'm now leaning against
moving all such pages under a common parent page. For now at least, I'd
like to just add them to a proper category, such as "User Documentation".

So, I'd really like to solve the category naming issue for user
documentation vs documentation development. I see three basic possibilities:
1. "Documentation" for user docs, something else for documentation
development
2. "Documentation" for documentation development, something else for user
docs
3. Explicit names for both

Note: One person (wiki username Jumbo444) mentioned
<https://wiki.documentfoundation.org/Talk:Documentation> that there is a
third logical category, docs for developers, QA, L10n, etc.). They point to
the French documentation wiki page, which divides its links that way. I
think this is good idea, but more of a presentation issue -- that is, I
don't think it would do much good to create a supercategory containing all
of these.

(1) might be the most straightforward and understandable for most people.
There seems to be somewhat of a preexisting custom of marking user docs as
"Documentation". In this case, it would be natural for documentation
development to be a subcategory.

(2) might better parallel the structure of other parts of the wiki, in that
"Marketing" is pages for the marketing team, etc. But it also might be
confusing.

(3) is, well, the most explicit. Presumably both would be subcategories of
"Documentation".

I can imagine people continuing to use "Documentation" for user docs by
mistake in cases (2) and (3), but perhaps this is just me.

Any opinions? Any other considerations?

--Kenneth

I've gone ahead with option #1: user docs are categorized as
"Documentation", following precedent. I haven't yet touched the doc dev
pages.

I've found quite a few orphaned pages (no incoming links), old pages, and
stubs, which I've categorized. You can look at the documentation category
page to get a feel for what kinds of things are floating around. Most
notable among these are the "HowTo" pages, which I moved into a common
hierarchy like the FAQ pages, put in a subcategory of the same name.

--Kenneth

Hi Kenneth,

I've gone ahead with option #1: user docs are categorized as
"Documentation", following precedent. I haven't yet touched the doc dev
pages.

I've found quite a few orphaned pages (no incoming links), old pages, and
stubs, which I've categorized. You can look at the documentation category
page to get a feel for what kinds of things are floating around. Most
notable among these are the "HowTo" pages, which I moved into a common
hierarchy like the FAQ pages, put in a subcategory of the same name.

I don't know if it's still true for en_US help, but by the past, the
files contained links to the how-to and to the Calc functions. Olivier
should have more info about it, but maybe there is a need to check if
links are still pointing to the good page?

Cheers
Sophie

I don't know if it's still true for en_US help, but by the past, the
*files* contained links to the how-to and to the Calc functions.

By files, do you mean the in program help files?

Olivier

should have more info about it, but maybe there is a need to check if
links are still pointing to the good page?

I found at least one bad link on the help wiki
https://help.libreoffice.org/Calc/Statistical_Functions_Part_Two.

Some wiki pages were under "How Tos" and others under "HowTo". I merged
everything under "HowTo", but this one links to a page under "How Tos", so
now it gets redirected.

--Kenneth