Time for a "publicly writable" Qubes Wiki?

[Achim Patzner]

Hi!

I’ve been spending quite a lot of time trying to look up things by sifting through the mail archives; even with search engines this is not a very efficient thing anymore. As there is no full-time staff for askqubesos.org yet there might at least be some intermediate step by people who are willing to spend enough time to summarize things (and either keep them up to date or give others who start out from that basis and add what they found out later) that are working for them. I’m thinking about things like my question about setting up TRIM (I finally found the man page — it’s “discard”, not “allow-discards” in /etc/crypttab), dealing with HiDPI hardware… Maybe even for philosophical wars (I could start with a “I’m a follower of the true BSD and /var/lib is making me so sick I’d like to throw Chuck at you”-type discussion telling everybody how stupid they are for putting config files under a tree _not_ called /<something>/etc).


Achim

[cubit]

26. Jan 2016 09:07 by no...@noses.com:

I’ve been spending quite a lot of time trying to look up things by sifting through the mail archives; even with search engines this is not a very efficient thing anymore. As there is no full-time staff for askqubesos.org yet there might at least be some intermediate step by people who are willing to spend enough time to summarize things (and either keep them up to date or give others who start out from that basis and add what they found out later) that are working for them. I’m thinking about things like my question about setting up TRIM (I finally found the man page — it’s “discard”, not “allow-discards” in /etc/crypttab), dealing with HiDPI hardware… Maybe even for philosophical wars (I could start with a “I’m a follower of the true BSD and /var/lib is making me so sick I’d like to throw Chuck at you”-type discussion telling everybody how stupid they are for putting config files under a tree _not_ called /<something>/etc).

It is my understanting that you can fork the documentation write what you want and make a pull request.    It is a bit of a formal process any not maybe accessble to everyone as a small bit of git knowledge is needed.

It would be nice to have a wiki of some type where it's easier to access and update.

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Every documentation page have "edit" button which will do all
that. You just need to have github account, just that.
The only (IMHO minor) difference is that you don't have live preview.

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQEcBAEBCAAGBQJWpz/4AAoJENuP0xzK19csA+UH/31IIPMnx8dBmBgN47TKRzkk
PRsasnMFL3Fyp7K1UIguD5x0rlWmNzJe3RkFW9/Hwo1y6lXLhG6YByjeTSpw1ctF
swH6HPnlAGEQXrOiuHb3V3McAbvPTdVz1gO3vrFMUQBVzuuav6PwYe54059uzU2P
IzfXA0yzLEMhrkDR73fRt6Q+T5t04emyPLON7r3ItWrJzOV53bcCHUBBZjMuBn79
T6D8EIQ6Us1JfWK7SK5CESjUv3hOGZpAivi2xhoDiy3LYSQUx27mdHhJpPAPmx3E
N0RZIjQM7VAjFULHZf1whqVwr0SO7Vq9pxHOkDX1XRUgB8JR4OlUqXqGXhBsCaI=
=dveX
-----END PGP SIGNATURE-----

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Tue, Jan 26, 2016 at 10:44:21AM +0100, Marek Marczykowski-Górecki wrote:
> On Tue, Jan 26, 2016 at 09:11:29AM +0000, cubit wrote:
> > 26. Jan 2016 09:07 by no...@noses.com:
> >
> > > I’ve been spending quite a lot of time trying to look up things by sifting
> > > through the mail archives; even with search engines this is not a very
> > > efficient thing anymore. As there is no full-time staff for askqubesos.org
> > > yet there might at least be some intermediate step by people who are
> > > willing to spend enough time to summarize things (and either keep them up
> > > to date or give others who start out from that basis and add what they
> > > found out later) that are working for them. I’m thinking about things like
> > > my question about setting up TRIM (I finally found the man page — it’s
> > > “discard”, not “allow-discards” in /etc/crypttab), dealing with HiDPI
> > > hardware… Maybe even for philosophical wars (I could start with a “I’m a
> > > follower of the true BSD and /var/lib is making me so sick I’d like to
> > > throw Chuck at you”-type discussion telling everybody how stupid they are
> > > for putting config files under a tree _not_ called /<something>/etc).
> > >
> >
> > It is my understanting that you can fork the documentation write what you
> > want and make a pull request.    It is a bit of a formal process any not
> > maybe accessble to everyone as a small bit of git knowledge is needed.
> >
> > It would be nice to have a wiki of some type where it's easier to access and
> > update.
>
> Every documentation page have "edit" button which will do all
> that. You just need to have github account, just that.
> The only (IMHO minor) difference is that you don't have live preview.

Ah, sorry, there is also a preview - you just need to click "Preview
changes" tab at the top...

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQEcBAEBCAAGBQJWp0DZAAoJENuP0xzK19cs+BIH/0pbWI4DSuk5xFbtRKjQSXAD
viWH5yv08809wo1yF14WHLlLd18EOAwV7QPn6ItmE+2dFpGtZvs7dr3tcheHzn3G
bxU4ZRJgGsIfjjT1jQmEkkn5YZosrCClOpDjSu4ewnXomLyxnpKqov1e5Fu/ayZs
xLgtxcfDQBFViJo3xdzE0nTBBg2AVQ5Wx6F6z1sQrPvyT6a1dPVJGa0B403ZCmu0
OIozaK73IeLjg6zO3nkDvva4kHsKikGpPMkPhreKWSxr1QfeLnqKQne/GBm6N+/y
YXUwTtRUYA/jmiKYFfWxgE4NS0rRHOEzrKMqJ258UqQMNSONqk7j91EmBGvU9Ic=
=vjpa
-----END PGP SIGNATURE-----

[Achim Patzner]

Developers… 8-)

> Am 26.01.2016 um 10:11 schrieb cubit <cu...@tutanota.com>:
>
> It is my understanting that you can fork the documentation write what you want and make a pull request. It is a bit of a formal process any not maybe accessble to everyone as a small bit of git knowledge is needed.

“Is it security the customer wants? No. It’s ease of use.” (or something alike, it has been more than ten years ago when Microsoft keynote speaker Steve B. was descending like the Donald on us after developers were *gasp* demanding stronger security functions in Windows 2000).

In this case it’s true. I’m using Tiddlywiki for some projects as intelligent, tool-free cross-platform document format because it doesn’t need more than a keyboard and something to write about.

> It would be nice to have a wiki of some type where it's easier to access and update.

8-). And it wouldn’t even be expensive to start this using a professional tool if someone wanted to avoid dealing with the usual tools: https://www.atlassian.com/software/views/open-source-license-request


Achim

[cubit]

26. Jan 2016 09:44 by marm...@invisiblethingslab.com:

Every documentation page have "edit" button which will do all
that. You just need to have github account, just that.
The only (IMHO minor) difference is that you don't have live preview.

It's still out of reach of some as it not just require github but also to fork the documentation and submit pull request.   At least for me when i edit a page I get

" You’re editing a file in a project you don’t have write access to. Submitting a change to this file will write it to a new branch in your fork cubi7/qubes-doc, so you can send a pull request."

[Wojtek Porczyk]

Yeah, what's wrong with that? Under textarea there is big green button
"Propose file change" which does exactly that. (And the right thing).


--
regards, _.-._
Wojtek Porczyk .-^' '^-.
Invisible Things Lab |'-.-^-.-'|
| | | |
I do not fear computers, | '-.-' |
I fear lack of them. '-._ : ,-'
-- Isaac Asimov `^-^-_>

[Zrubi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

It was already discussed several times. You can read the latest here:

https://groups.google.com/d/msgid/qubes-users/20150720200721.GC2196%40ma
il-itl


- --
Zrubi

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJWp28oAAoJEC3TtYFBiXSvDFIP/iwwuDXU/FqXRNA0TAJImxzr
ikJJKgSkSEqESKu15FOw3NyZ+UiH7b3u/qMuJtJrnlDv0kISbnucLrav8JEKpC4a
BZXHQZJmCu1QLcnAgfYPn5gpINEa4ptTTGcddif50z7PUmQ31jIvfwOMgt5Gwaqz
lxPghYUWzwmpEP16jBQEyssA06izLNbGoZew6bEy/VVZy4d4IOH9GDayWzGyePkw
WkRx55lNTpUedI+lCF2EYmq4FZq5vdA+gLjY5sV82f+qbRMtLseTfEDTWb1wTTy6
ZuKMM1Ofx1iTcVTCq9gkNBMfz8E58VCADzo0fbBtMk3guDUCYmFQO0xVXNcY/4CG
GJAcuHnbCwLQo7YH0nD/TC6yNOMDsDzXzSZgGXseWKFKK3nlaUPi125/Pb6Gvaht
r9th+CMCo8OKjcoxh3Fg3EnmBbFatHt58JftcldwqUsEVFxeZEnXFDIAy3e1yLNV
NcQecp7oSvQwXwhulbsWf1jztRB0/4NkmxwEMvYQlA92l3wsiIoZUU8Vuq955693
yuGacRWimQ3U99qnK3bHrhrW3UDHdEn12K41EwmgHOzaCbY2HmgLm5dJftdcsEHg
4NhADhBHeBTHcscN3APVcDJkAkXo3CYRgvPKRPxSKYHmx5700xqa44ZKE+yfQQIB
q6UXgHlyu2HQChb+9B9C
=ZSpS
-----END PGP SIGNATURE-----

[Chris Laprise]

On 01/26/2016 05:05 AM, Achim Patzner wrote:
> [...] years ago when Microsoft keynote speaker Steve B. was descending
> like the Donald on us [...]

:D I love this! Except the Steve did not have a "hair surgeon".

LOL!

Chris

[Achim Patzner]

On 01/26/2016 02:05 PM, Zrubi wrote:
> On 01/26/2016 10:07 AM, Achim Patzner wrote:
>
> > I’ve been spending quite a lot of time trying to look up things by
> > sifting through the mail archives; even with search engines this is
> > not a very efficient thing anymore. As there is no full-time staff
> > for askqubesos.org yet there might at least be some intermediate
> > step by people who are willing to spend enough time to summarize
> > things (and either keep them up to date or give others who start
> > out from that basis and add what they found out later) that are
> > working for them.

> It was already discussed several times. You can read the latest here:
>
> https://groups.google.com/d/msgid/qubes-users/20150720200721.GC2196%40mail-itl

I read it but there was no reference to the current situation where at
least Marek is seemingly spending lots of time to answer things that
could be found in the mailing list (just look at the discussions around
the ArchLinux template) if they could be easily found. If there was a
"self-service" section this _might_ be better.

And seriously: Adding your notes (about topics you already know at the
point of time where you would want to summarize them) using git might
appeal to hard-core programmers but the rest of the world will just walk
away with a big WTF? sign hanging over their heads. This approach won't
work if you want to reach a more general public. Or why do you think
there are people looking for answers in bloody _Reddit_?


Achim

[prance...@sigaint.org]

> I read it but there was no reference to the current situation where at
> least Marek is seemingly spending lots of time to answer things that
> could be found in the mailing list (just look at the discussions around
> the ArchLinux template) if they could be easily found. If there was a
> "self-service" section this _might_ be better.
>
> And seriously: Adding your notes (about topics you already know at the
> point of time where you would want to summarize them) using git might
> appeal to hard-core programmers but the rest of the world will just walk
> away with a big WTF? sign hanging over their heads. This approach won't
> work if you want to reach a more general public. Or why do you think
> there are people looking for answers in bloody _Reddit_?
>
>
> Achim

Agreed. The Qubes user base is growing fast and it is getting mainstream
attention. That means an influx of new users who aren't tech literate.
That's not compatible with the current development-style approach to
discussion and documentation.

Also, I'm sure Marek has much more important things to do than answering
the same question three times a week. Though, I appreciate him doing it.

[cubit]

27. Jan 2016 15:01 by no...@noses.com:

And seriously: Adding your notes (about topics you already know at the
point of time where you would want to summarize them) using git might
appeal to hard-core programmers but the rest of the world will just walk
away with a big WTF? sign hanging over their heads. This approach won't
work if you want to reach a more general public.

This is problem for me too.    I tried to make small change to test how easy it is to contribute.   I can say that the process was in no way user friendly for a lay person and would put me off trying to contribute more content unlike a more accessible wiki.

To edit I had to

1.  read qubes documentation

2. see something i want to change

3. click edit

4. "sorry you can't edit, you must fork the repository" 

5. sign up for github

6. fork qubes doc repo

7. edit in my repository

8. commit chage

9. great now I have a branch of my fork of the documentation what do i do

10. some how manage to find a pull request option

11. realize I have made a pull request to merge my change with my master branch not qubes

12. get completely lost

13. delete my fork

14. repeat steps 1 to 8

15. not sure if i have working pull request at this stage

For a wiki

1. read wiki

2. create account

3. make changes

But I understand wiki has its own set of problems mainly it opens up for possible quality issues

Or why do you think there are people looking for answers in bloody _Reddit_?

Is reddit.com/r/qubes a bad thing?   It can maybe be more accessible than googlegroups at time as no requirement for email account.

[Achim Patzner]

On 01/27/2016 09:13 PM, cubit wrote:
>
> To edit I had to
>

I thought about this for about 30 seconds, shut down my machine and
spent two hours on biking. I found out on my own hw to get the i915
driver into the initrd image (man pages are a great thing if properly
written) and I don't really feel like sending additional hours on
writing down how to get a fairly recent machine working if I have to
hand-forge my tools before getting to the task of writingthings down.

> But I understand wiki has its own set of problems mainly it opens up
> for possible quality issues
>

I'd say that this is a "you get what you pay for" situation. But I don't
know if the current web pages (see "TRIM support") are always much
better in regard to quality control. If it was a wiki page I'd modify
it, put a reason what I did and why I did it in a parallel discussion
thread if it wasn't self-evident and that's it.

> Or why do you think there are people looking for answers in bloody
> _Reddit_?
>
>
> Is reddit.com/r/qubes a bad thing?
>

Not so much if this was a project with a user base of more than 100000
and a support team that could look around everywhere. As it is right now
it might be a better idea to have all the knowledge in one place.

> It can maybe be more accessible than googlegroups at time as no
> requirement for email account.
>

Google groups are (from an user's point of view) the worst possible
solution. Hard to find the latest information about a topic as there is
usually no hinting at relevant information in other topics, no way of
modifying existing messages for updating information and no more quality
assurance than anywhere else if it must not steal inordinate amounts of
the developers.

I can live with the current situation although I've got the feeling that
I'm reinventing wheels left and right but I can see how this will look
to the typical end-user.


Achim

[donoban]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 01/27/2016 09:45 PM, Achim Patzner wrote:
> Google groups are (from an user's point of view) the worst
> possible solution. Hard to find the latest information about a
> topic as there is usually no hinting at relevant information in
> other topics, no way of modifying existing messages for updating
> information and no more quality assurance than anywhere else if it
> must not steal inordinate amounts of the developers.

Not to mention that many users come to Qubes trying to improve their
security/privacy. They found Qubes, the philosopher stone, and then...
¿Google? hehe

On the other part, I also think that a Wiki would be nice but maybe
(since devs don't like very much the idea) it should start being in
some way unofficial. It will start empty, then it will grow etc...at
some point Qubes will add a link "unofficial Wiki" and some day (maybe
even few days) it will be "clearly" better than the official and it
will be easily changed.

Well, ff you and another people think a Wiki would be better. Do it!
If it's good it will be official sooner or later. Maybe it's not
official but Marek will answer here with a link to there ^_^
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBAgAGBQJWqUJEAAoJEBQTENjj7QilQYYP/0J5bOX+sBODEIOq1qKueLWD
sZ6BXK2DYXlexDBvZqlqlHqr3bXsIXL3ec9gEKU1JxOZvcburgBC23MoI6hVbgER
xKupsT0WxTf0mRFm7KUTgMrkLXfzW0KfVmFjCODh0veylGtWk6XucME4t8kJSnfS
TIbWzoqSVG7PtwTS0nsIYhKNCHpLbBL32TZUgQ9E46CeQcV1l+wphgIHch81bbfm
a5oM+/1bke6/yVsZlmqosArRiSkC9yBnUoyrw6TBjjBM18neGN3kjRZ7vIEGRpcH
GEACyMXDR4n7Z2wUwj2JQhzjZKIH7WOskXaVDEexg487oooq0XlERII2rcM0BxX+
fPJGoC/bQ9RfA+oSP3tF4cRUHzmpQlghGRWn7r422cIGr6lTk9KqNJkea6b3dior
hrPgXAeMhy7gbM5O/3EsBcnxIeJDoR+Fh0FlMCFg5x6WBRK1BCByAEOhRsiomDhw
WUuKQk5Qjl/mSZ8y1EKGSbVG02yUWzxhOdHlM44rLFTWJTjqlSfTzroAsEsFegKa
SAIItP39FpbVpxXa4vxDFev+wLTCNbjYPytoc5/EGodDMglf7+AewKnW83fOrE2t
Tch2dNFeq+x5gDICn8mnRJZocAwvkRGsBrZZjMEkLtSehT3ZsJA+gZvA8jyF880W
YdCzLvHFHOtcIq3EUZj9
=lO/K
-----END PGP SIGNATURE-----

[J. Eppler]

Hello,

I don't think that the current wiki is the issue. Since github makes it really easy to work
on the wiki in a graphical way.

On the other hand the qubes user base is expanding fast and many questions are the same. It would
be nice to have a QA forum or something like that. To actually answer many "noob" questions and
more important find them again if they are already asked.

Best regards
  J. Eppler

[Tim W]

While the github way is certainly not stupid easy like wiki we are also not talking about a dealing with a system ,meant for editing all sorts of topics we are are talking about being able to edit part of a  very technical topic and the center focus of that topic is security.   With wiki any sort of data could slip in with no review or oversight until someone catches it.    

I have NEVER added to github or had a user account until Qubes.   I have never edited a doc under github until the current situation where I am working on updating the archlinux instructions.   With that said once you know how to edit and send changes I doubt anyone that should be editing a Qubes doc could not follow it.  

When I see people's comments it seems the real issue and I would agree is:

**** There are no clear direction of HOW to edit the doc inside the Qubes Doc.   It requires people to dig or experiment.



The above can be easily remedied by  adding a section to the Qubes Doc on how to submit changes to the Qubes Documentation. 

If there were clear directions of the process I can not see anyone that has the knowledge and understanding to install Qubes and setup VMs having an issue following them.

** Personally I would NOT be OK with a system that would allow people to just make changes to the doc without oversight by the ITL qubes team before those changes are made live.  


Cheers,

Tim

[Axon]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Tim W:

Well, it's already in the README:

https://github.com/QubesOS/qubes-doc/blob/master/README.md

In particular, the part that says, "To contribute, please fork and
clone this repo..." including links to the relevant GitHub guides on
how to fork, clone, and send a pull request.

Is there anything wrong with those instructions? Should anything be
added or removed? Does it just need more visibility? Does it just need
to be duplicated onto a page at https://www.qubes-os.org/doc/ ?

>
> The above can be easily remedied by adding a section to the Qubes
> Doc on how to submit changes to the Qubes Documentation.
>
> If there were clear directions of the process I can not see anyone
> that has the knowledge and understanding to install Qubes and setup
> VMs having an issue following them.
>
> ** Personally I would NOT be OK with a system that would allow
> people to just make changes to the doc without oversight by the ITL
> qubes team before those changes are made live.
>
>
> Cheers,
>
> Tim
>

-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJWqd7SAAoJEJh4Btx1RPV8FgIP/Rm8vr7+LM6bOoR+WkfXwTaq
560z7zhSAP3kRUX45r0F5fO3OMWn89a+fJ9p6wLIqkd1WqndtDpgE8o8QvrUBtp3
8XGSCLAJjFfg6bmLR84tPcp0kjRw2P7gTr4cbhgfP5zGAA3aVFvwq90WnNl5x4gL
tQOt0S/cIe2ZVludsvicYH7UJg+ISwmjLOnvKeSMUEEhTJHyZZUV4DRLezgz4pIj
97J4uFav+sLkRDLfl3dRurXjW4w8lfifpIkKnU46k2ApcSyh5laYJlSHtve1ATeB
NnJzdySGVGpsTGQBzch79dvXe1EEH0kb3Xy0+xTezLncUnw6WG3NMeTgb3P52hu4
IJVddkZqBGmPxS96KQHUAhs/Gj5sTvxI0+mqjaEAiogLUJPSKDd80ME99XRlEmk/
5pXyjqi3WvXYZxTSqUKHILDsshp5X+rf3pWXwxe39QG4dPASFlDEmE/h7Dhr416J
cZIFNLocOT+2r0HVym1us7WnJaTu2EE/vpm8cXn9iGdqdZfVZvVtALPHBH3AuXxX
Vu8VwnfbOWnWF5oudk8prgb4jLjCwVlXN85iDnScuJgt6ffWx4DSYJb5BCEF0PwK
MftRiQJYlJ4czXh2PnjGsOXbmNZ191UoDqaaLTxLt8nUk/hOBGoRR5Y6LbE7eSjk
sYvwj4J6Bo05mlhksrQ9
=GHJl
-----END PGP SIGNATURE-----

[Zrubi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 01/27/2016 09:13 PM, cubit wrote:

> To edit I had to
>
>
> 1. read qubes documentation
>
> 2. see something i want to change
>
> 3. click edit
>
> 4. "sorry you can't edit, you must fork the repository"
>
> 5. sign up for github
>
> 6. fork qubes doc repo
>
> 7. edit in my repository
>
> 8. commit chage
>
> 9. great now I have a branch of my fork of the documentation what
> do i do
>
> 10. some how manage to find a pull request option
>
> 11. realize I have made a pull request to merge my change with my
> master branch not qubes
>
> 12. get completely lost
>
> 13. delete my fork
>
> 14. repeat steps 1 to 8
>
> 15. not sure if i have working pull request at this stage

That is simply not true.

The current workflow is just as simple as you described your wishes:

> 1. read wiki 2. create account 3. make changes

Because of that big green 'edit this page button' will do the rest for
you.

> But I understand wiki has its own set of problems mainly it opens
> up for possible quality issues

This is another issue - and Joanna already made several statement
about what they prefer. If those are not changed you will never see
any kind of 'free to edit' wiki ewer about Qubes.


To replace (or in addition) the current mailing list to some more user
friendly solution - like an open forum - is something I would really
prefer.

However I see the problems involved:

- - it will be never be more secure or more private that the current
google groups. Instead it will be always depends on the hosting
provider + the OS admins + the forum admins + forum engine.


- - Because a hacked Qubes forum not a good marketing - we should make
it secure, or we have to use some 3rd party forum provider as a
service. (Like google for the mailing lists)

- - If we want quality - the Qubes User Forum should be moderated - so
we will need a few moderators as well.

- - Running an open forum would involve a lot of legal things as well -
so we also need an IT lawyer.


Most of the 'we need a' thing described above are costs real money.

- --
Zrubi
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJWqd9sAAoJEC3TtYFBiXSvX+QP/3+wfBBufhjBhLTZGWe3vk7M
JdCtAw4FxVtRLzhdgJzs672C8sSzB0VGF2f0w9tF/T/iYMte7wqseCXtu6k5c/ku
PKVj1uKxX4crfKJFn41TqHRxNF00ygAhCj/t6vvhsPFeSICvqK1DsWGca/S0Fm1E
SEiDiyuPBDhN/y87YWS5WHzeMZV+vAamvAJ5L3naX2tx86gZtFKzJxBlDP9fLCI/
tivNSrAeXoz2vkdtSPP8DUej+e7XBHy8qtnPqhzVr2lTjOVx5W2R3eu+Tj1xPnMk
naglcgwci3AZTafVL62HkbxIUEJjz8aS5vIUA3+/xgNhF5288OfPGtukiGz5/0Kc
8nNrCom7pCKHPbiB5ojNuGi8upLKEcqoZmk79MsS1qXwNWjhQw8z0Vr2eUCM2UBX
QjUMohxLAJBp3XXnlCRKGN8VNbcixhCCUOFgqYzOOvdbMGxzXBfcYta8KUajRMs+
PjVqm/bnP5bnPUaWqRDDMq43WMfq6PIprsn4TrOxOsfEEpRqbt7JDGfnJ06wNRpv
jQ1Q2IFmvSRMw4ApiZGhLzcIad3HhlYzX/43fHBnXvaUfXluVgna3O9jxXgVh53J
chbv6swP7kPq1rZCJlLBgM3uKrZ6EvqUq0b87ECPUUhFrcw2DZtF0YPMfJl+nTvN
5niHIhh2htWUmdwpVYjj
=fl2E
-----END PGP SIGNATURE-----

[Zrubi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 01/28/2016 10:27 AM, Axon wrote:
> Does it just need more visibility?

Sure it needs - I've also failed to found that page :)


- --
Zrubi
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJWqeBjAAoJEC3TtYFBiXSvCvUP/RraH/AsMwpmBQFVOnHGB+9j
7rMQDKv3fUCftYN5zFZ62QsNV9EA6VEw8p6equBFVieDZAgqfwkPts9QdVZrk20m
xdm3vLTau141YqAbPBdvzOljlMshgdPZt3U4IXPKoOoz6I0v77Jr2/SebIVlaGzJ
u1DPnLDbiDw3Q4bLD1ge/3yQ4NkDjIJLE93cN7yLXSJJDg/44O4E/ThELmOuymug
6zWQ32ETfBwfiFAe0vS6ZIyh7kzVmoYy54Q49pTPtQH+zPkjsXIM+XtsgyA60ZPt
j+kVmtmz95+O8AgLgXi5cb+Q5KbN52bQVH4cB1UEDz5iQPYqf7w5d8D/xiY2/F/9
HT9wm2M6crLYOe+bv9qYx63O7R5bCiixkCydvERZ80fVGTEwxZ2vs5ESZURsG/k3
Qg1i3G3CkFygZdth01n3Jdy5Xev5s0s2NnrptCZNuxeGQX3nHH2p84YX2UR5rda8
Ad+WCoXAxRZfzWXb/ZRSE03zygne5WoOU0dcC+RYjrsK+PzE2t9rH+qeaHFbQPVN
stxCDXXC2Bjb2JTOzDfhJpb0m176Nq3u2ssmuVb7+oT4ix8e8dfur6dE1eymI9rv
XzVlKlWYSHrExG5XmzYzMPCMC8UYcHry3Y57pCwINC6Pc0pyCfoquPLO54uMCKQu
21pVRV1n2q2JP0bjSFKT
=dQjE
-----END PGP SIGNATURE-----

[Axon]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Zrubi:

> On 01/28/2016 10:27 AM, Axon wrote:
>> Does it just need more visibility?
>
> Sure it needs - I've also failed to found that page :)
>

Well, it automatically shows up on the main qubes-doc repo page:

https://github.com/QubesOS/qubes-doc

And, actually, I forgot, we already have a page in which the same
instructions appear, all about how to contribute to the documentation:

https://www.qubes-os.org/doc/doc-guidelines/

I'm not sure how else to make it more visible for people. Suggestions?
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJWqeTCAAoJEJh4Btx1RPV8EZIQAMcXodwWEVwgh3LH+E9UQuU6
FO0FaApuoo/NA0Xq0ZDkrtujF+kO4RceDazcfw7KctC4eKDHaq0zU6rUPO/qejWR
WsgT7tx975zUKUad1oYEhrYMWK7SlBmAA58qaxBl1FhBxB0+FaRKR6G4MQ7lBX6r
PaC01RM0msZyKxIxEuFF19Zud1I91qeeoo9uioc2EAtc7Q5z8SVJ8wg2gWtFwDvT
XIKCmcdl1oSDUCyuzAMpC/zUzNod+RMz9f1pU5GCNth0I2Z5TCBdCvs7WPaOwOlz
cHzrEGCllv3xdtWF3Gqk+9ppEcGQLL8bytWnp86xi4STJpXjOeR2VzvsXJJvyl+b
qD4yrIE8tkHqQDaE+vOgYX2urbSI6mOT/YTfv2e5w9qMsMQCLG4wHtr6d/zMRF/H
/uQSEmM2W2KWe18Fa05WrTvefwGhkFvXq1j4aYuRUT6eUpdp9w9rSGaKLqs1lCvv
fVFS9PwJ+gS7t2HoDVZrZwKGKWx9mskZwDfSqGqwOQkMU9UMlW3ry5Bqst/PtSag
nI7ZikoyMVkMjlOl8DdxJJ5zcMRfeJuqCSPNTGB4smulFn2If4PUQMHdaqOzAMnq
YN4wQjylzvuP9hVKVg8AngWW6LrgQxexfzh/qIKmuRQXNAZOB+ZFdEQH/mHRrPdm
9zlnDbIcKsMopGt6nmVa
=uHJt
-----END PGP SIGNATURE-----

[Zrubi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 01/28/2016 10:52 AM, Axon wrote:
> Zrubi:
>> On 01/28/2016 10:27 AM, Axon wrote:
>>> Does it just need more visibility?
>
>> Sure it needs - I've also failed to found that page :)
>
>
> Well, it automatically shows up on the main qubes-doc repo page:
>
> https://github.com/QubesOS/qubes-doc

Yeah that's OK, but I don't think people are going there directly.
Including myself. :)

> And, actually, I forgot, we already have a page in which the same
> instructions appear, all about how to contribute to the
> documentation:
>
> https://www.qubes-os.org/doc/doc-guidelines/
>
> I'm not sure how else to make it more visible for people.
> Suggestions?

I would merge/link all contributing related things:
doc/coding-style/
doc/doc-guidelines/
doc/reporting-bugs/
security/ - as for reporting security issues

to the contribution page:
https://www.qubes-os.org/doc/contributing/


And this should be linked from some 1st level page, for example from
the TEAM - there are a nice list of the current contributors so the
link how to contribute would match nicely.

and/or a 'how to contribute' link to the footer as well?
Extending/merging with the 'donate' thing for example?


and maybe a direct link from the /doc main page header to the
doc/doc-guidelines/ as well?

- --
Zrubi
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJWqexvAAoJEC3TtYFBiXSvEUsP/1FqAj55FbfIwcsGhdXWWRr4
Wl22vMWFQvrX/cMQovr5lzmSehvL55F8moCsGcWUjeQj8NuYX5dzqIyYPOH0+7JA
pvVpU8umcz7GCvMi1lH10DE1zbDxTsPbTvjV0gVe/1brUXsw/k8OSQ1nozD/w5oQ
W/jT0giGsgSkNWd5d0axZy7DGguqdRHHGw8YupG4xtnMmb//kwAHI7eq8FK3I3xw
bSciYb+eKhxFSNuYsUSgcuHQHyiqHu6F6mx6Hrx/koQUHU25Aj877zrz1Tkg6Kls
heMxI1QfGODq2gaDl40cC2nDVyKteDqQlnRuhg8dQRYy+q9AaWDBLXwOji0F3xdG
/sK/oZMdpRe51falnAcKfZkZVLmuSE+VXTCUK+G21Hkkj6Kbq9WYc/YZBl/sf3ti
8YPbBk1Pw7nSucuHOLOnJ2va+lJjwEjEq677P6nRojzXNy6t/xTg4TLsYxzYy9Z4
qUl5JGcEIU2OMEUteAN2mEr49LmUCW9DepUtLRR6QTxYBiZRX33EDkgMfo6+fRuG
sy5Ah4PIE+aAwn2lB2UDEDdFzvUF15EZGSXfh5/K7XmurvYU/6F6E1iOXN9kh9PD
KoiupXZQqx9VyQr4cm7VozO11DmtFg1UT2NljjJd2NSoYXlBBPMK516k9/LtN9E+
9ErAscptIVQWoE38cl8D
=jW48
-----END PGP SIGNATURE-----

[prance...@sigaint.org]

Hi Tim,

I had in mind a two tier system. There's the official docs, which should
remain overseen by the core development team. But that limits the amount
of topics they can include. Then there could be a wiki as well, which
should be covered with warnings about not trusting the content because
anyone can write to it. I believe that open source software is better than
closed partly because more eyes look it over and spot problems. The same
is true for a wiki. If someone posts something malicious or incorrect,
then it will be spotted in time and corrected.

If qubes wants to be a mainstream, end-user operation system (which it
seems to), something needs to change. The current documentation has
advantages, but searching through the archives, having it hosted by google
(is there any reason google couldn't manipulate the archives?), and the
lack of content in the official docs are a problem. If not a wiki, then
important threads from the mailing list need to be turned into new
documentation pages and approved. And progress on that seems to be slow,
though I appreciate your work on it. At the very least, add more links to
good mailing list threads to the doc page (there's a few, but so many more
could be added such as the openvpn revisited threads, archlinux template
building, etc).

[cubit]

28. Jan 2016 09:29 by ma...@zrubi.hu:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 01/27/2016 09:13 PM, cubit wrote:

To edit I had to


1. read qubes documentation

2. see something i want to change

3. click edit

4. "sorry you can't edit, you must fork the repository"

5. sign up for github

6. fork qubes doc repo

7. edit in my repository

8. commit chage

9. great now I have a branch of my fork of the documentation what
do i do

10. some how manage to find a pull request option

11. realize I have made a pull request to merge my change with my
master branch not qubes

12. get completely lost

13. delete my fork

14. repeat steps 1 to 8

15. not sure if i have working pull request at this stage

That is simply not true.

It is true and you know how I know, it was exactly what I had to do.... 

It is not necessarily what people familiar with git/github but as a new to github user it was the steps I had to take.

Not user friendly at all.

[cubit]

28. Jan 2016 14:46 by prance...@sigaint.org:

I had in mind a two tier system. There's the official docs, which should
remain overseen by the core development team. But that limits the amount
of topics they can include. Then there could be a wiki as well, which
should be covered with warnings about not trusting the content because
anyone can write to it. I believe that open source software is better than
closed partly because more eyes look it over and spot problems. The same
is true for a wiki. If someone posts something malicious or incorrect,
then it will be spotted in time and corrected.

The archlinux wiki is a good example of user contributed documentation that works.

https://wiki.archlinux.org

If you want to know how to do something (even not related to Arch) chance are it been documented thoroughly here.

No such nonsense as "search the mailing list archives".   Sure it the answer might be there but you have to be reading through multiple threads and usually try to figure out which bits of an email thread have the correct part of information.

It is really not user friendly   :-(

[Jeremy Rand]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

This exactly.

Qubes is a security-critical, internally complex system which is being
marketed to people in dangerous situations. When incorrect
information gets posted on a public wiki and end users believe it,
people die. I am not exaggerating. It will be of little comfort to
people who get arrested, tortured, or killed that the incorrect
information was removed a few weeks later by another editor.

I'm a Namecoin developer, which is less commonly used for
security-critical things than Qubes, but which aims to end up with a
similar user base at some point. The previous project maintainers
decided that a wiki was a great way to encourage user involvement.
Guess what happened? The wiki got filled up with incorrect
information, and no one was motivated to correct it as fast as the bad
info piled up. We're currently in the process of nuking the wiki and
starting over with a GitHub-based workflow, because that way we can
actually review stuff before end users see it, and there's more
pressure to review things promptly since we get email notifications
every time someone comments on a pull request asking for us to get to it
.

The set of people who are qualified to write Qubes documentation
safely is a small percentage of the people who will be using it.
People who cannot understand how to edit a document on GitHub when
given the right instructions (which as Tim says, could use
improvement), are unlikely to be qualified to write Qubes
documentation safely.

Usability is an important attribute to strive for, but let's not brick
security in the process of gaining a tiny amount of usability. People
who want that balance are happy on Windows.

Cheers,
- -Jeremy Rand
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJWqj9yAAoJEAHN/EbZ1y067g0QAKRDB9PiSytjhkfQ1UvBmh1S
PtSUdcDSpIi3OHnSAPxZcwCXnCkcRlVNmwm4qjKTj5j9aNSwagwI3UeF6EiWgNuk
uDVwewU2dusVpVDS/ZZXfaAwEbqDn4hFIr8lxk7T2IbCSEX3kKpNPVvLzHHZqga2
g1iBKHOyysd3KEJEwCP7B3+0w5kMUj3RhQ4IgwbUcb3gMBWyrXRbId/O1FEsTA9+
0AKdGcM5YwQ6DcBrklGC9JjOdkvGIy7ixFnw5vCLjqxo0VIK94JdJg/zeEMADKBy
crAkUCLjxc7doJ+a24/zc5ChNsbkW1cPRrhSNIKDMMEl2HXnBcYZn2vpwx9BDhuh
9jPbyNAnRUX7Y0j248aPFWqKaHKBv9MNzQEXtTjTlQjJ8z1OwFmDl6etDdDHdbM4
9FCc7bzmfQoXjb9272nFRnlvhNMHcIXOnTaCQ71Bh3FYEmChDv+/ZYV72too57eJ
zMUm8UKOT0lObYyf7GYKxxwrQ8M7sfljlWN4EAgSsqv5Wzcz/0uxZzenndpAuALn
FPWjds4WJKlmb69pok5UH/Z1CW/ODadAEZU/o9fIaG/Bt4hBakvT+tre+DUtxk+E
arVO5Wi4OuaAF+37n/kI+KazYnOymQpkw16QQ/d1gVLVP4qia7MxAQiHVF9ZCjyG
QXSV+5+2yAPtJKEqcNFm
=LBpF
-----END PGP SIGNATURE-----

[donoban]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 01/28/2016 03:46 PM, prance...@sigaint.org wrote:
> If qubes wants to be a mainstream, end-user operation system (which
> it seems to), something needs to change. The current documentation
> has advantages, but searching through the archives, having it
> hosted by google (is there any reason google couldn't manipulate
> the archives?),

I don't think Qubes wants to be "mainstream".

I hate Google, but if you don't trust them use PGP signatures to
protect the integrity of your mails.

Since the documentation is stored with git, it has also cryptography
protection so it has great guarantees of not being manipulated. I
wonder if a wiki has a similar feature for guarantee authenticity.

Anyway, while it is something very valuable for source code / personal
public opinion, with a wiki where changes are easily revocable and
there is some people revisioning news changes etc... maybe is better
having something more easy to edit than so cool like git.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBAgAGBQJWqyRxAAoJEBQTENjj7QilNygP/03zcRMIm0Idjh2MR2Isrcb+
vPeoncRwwQwD5YpWRx0tZvzx9wT9iYM6Q2/zjufNqcEASGZejMp+ixJIqQ2n6Ker
ZnWQYr6mW70j+MGF4MBg3idweueoqMUZcCsdN/H70I1cUvOFoC2qIjmhnxJW/vKe
4SpRVYsj1+TqX1T9EoLsy/ryeEFXA0khFwpy0q4ixnO8on409I4wN4Zvt/q/6LMi
mFU3zzZhidtYoeTNQ5aBrUjvSk04XxCLWnIhs2irauAZ/iRoktHtsKPBhercjaIY
p7luML6kmhO0jG/yFOWB21eYtfpWWDNBsEfH5g+7YC++bIr/FXysSG23fCND/khx
8GBLcShanLTzk/IGxgt+XPYZc9Lnl+XcvOcQsQjgGGC04hSUIsHCABi3cd852UJn
ENUC7B+1VywIuPgVWIdR22DuLDmk2JQbp1fguwbf467PDi8Irc6mfnFIGiH3ls/9
Sinmhd9fRCexadVofaJgNubVg0HRsNX7+QF7gNbhFm8IvJWo6lmn0gO09aWHM9pL
QUgAAYJ41EYKNy1eT2Rmvg7ot7SSonlOKg1Om3sDSWfi0TQg877l68Yqvb7L4yLE
bJM/tKtFJreR4+7scnhFWJnPXbBk1b/O1pWexFmIzN2HJ2tUElmBEn91r0Xm2DYR
DhKVJxoyVFwf4ou1jrpu
=amx8
-----END PGP SIGNATURE-----

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Fri, Jan 29, 2016 at 09:36:01AM +0100, donoban wrote:
>
>
> On 01/28/2016 03:46 PM, prance...@sigaint.org wrote:
> > If qubes wants to be a mainstream, end-user operation system (which
> > it seems to), something needs to change. The current documentation
> > has advantages, but searching through the archives, having it
> > hosted by google (is there any reason google couldn't manipulate
> > the archives?),
>
> I don't think Qubes wants to be "mainstream".
>
> I hate Google, but if you don't trust them use PGP signatures to
> protect the integrity of your mails.
>
> Since the documentation is stored with git, it has also cryptography
> protection so it has great guarantees of not being manipulated. I
> wonder if a wiki has a similar feature for guarantee authenticity.
>
> Anyway, while it is something very valuable for source code / personal
> public opinion, with a wiki where changes are easily revocable and
> there is some people revisioning news changes etc... maybe is better
> having something more easy to edit than so cool like git.

Thanks to github interface, editing a file there isn't that hard. Take a
look here:
https://www.qubes-os.org/doc/doc-guidelines/

@Axon I've made step-by-step instruction there, with screenshots of
every step. Do we want to make the link to it somehow more visible
than the bottom of documentation index?

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQEcBAEBCAAGBQJWq16CAAoJENuP0xzK19cs5zQH/3vstmojUQjE5naxtD+YYBjQ
wYsomb8CWogCASHa/IBMIJUsQ0xvRh+iio2ZFrvMsdfie3kHc6KaBumhxEouQ4AW
pBhJOf31vVyyo4p/hx2BbCzFaI9JJM39WU48q+mAuJnrsZBYEBYH9xIocgPhWkJw
cF/UwXVW7vXLXks67TE13lI/ITZaEBH9vR8lmJNYDnO2Qnp0votOfPhNTI5sd/yU
rUdI/JKgCwLUzi/ZD3BLaSEE+eGGPbZsHANRK65vaw8Y5L/soyRriCEBLAqrNtsn
gdZ/iSUrL4WuKXRTqEdhxaRCeK7w8N3f44kz8ncUXdTuJZB0lVn4CNkdXtqJSvQ=
=QiZ2
-----END PGP SIGNATURE-----

[Axon]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Marek Marczykowski-Górecki:

> On Fri, Jan 29, 2016 at 09:36:01AM +0100, donoban wrote:
>
>
>> On 01/28/2016 03:46 PM, prance...@sigaint.org wrote:
>>> If qubes wants to be a mainstream, end-user operation system
>>> (which it seems to), something needs to change. The current
>>> documentation has advantages, but searching through the
>>> archives, having it hosted by google (is there any reason
>>> google couldn't manipulate the archives?),
>
>> I don't think Qubes wants to be "mainstream".
>
>> I hate Google, but if you don't trust them use PGP signatures to
>> protect the integrity of your mails.
>
>> Since the documentation is stored with git, it has also
>> cryptography protection so it has great guarantees of not being
>> manipulated. I wonder if a wiki has a similar feature for
>> guarantee authenticity.
>
>> Anyway, while it is something very valuable for source code /
>> personal public opinion, with a wiki where changes are easily
>> revocable and there is some people revisioning news changes
>> etc... maybe is better having something more easy to edit than
>> so cool like git.
>
> Thanks to github interface, editing a file there isn't that hard.
> Take a look here: https://www.qubes-os.org/doc/doc-guidelines/
>
> @Axon I've made step-by-step instruction there, with screenshots of
> every step. Do we want to make the link to it somehow more visible
> than the bottom of documentation index?
>

Thank you for doing that! And yes, Zrubi offered several good ideas
earlier in this thread about adding more links, which I will implement.
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJWq25PAAoJEJh4Btx1RPV81IkP/0kjLRB2vBT6k4s2dwAShdUZ
1CCSeRw6pmy46WDKoSNeN4At6qrT6JfMqQ9pgjwd/L86D5hBxzdVEyiqpM6CzEYe
blxwwgR56hZqCkO7pgFuO6v8SbmGv3EaaL3hx7xUdLB6JuM4ehpKJVhyyj54dFue
jAVV6xRheET8Zj5FkAOfw7n29icUdYg1RyNPcJ7Ozon0h3Jf1Qr/Ag1aCUCPSzrj
u0qgjTbpEhOVOey8a15VoRRSIlnQ3+/aaYBX6rIn438+Us8IFtHx3j5lc70GrbI6
FKyxWqm4pCtJm7kOTZ8t6f6U0zetCUCv0ygm4fz66h22qzg1B/TkUWC2prwbduuo
9cB1d4RJ3O8Ksgo00oZZ7oT4WX1RG0FHDnZXi/62wDMCVDwILea6jEuJDG7lcyeV
+2txUQPxR3SYyyqYxV9DZoh1uOwIOtJbj8gvwy0z51eK0epyZLwTEFj76xK7K5uz
eXPs2APCpTlgMTAx+W/770MFHck7//nZH/8fHWGXDnYP4RECN5W0jJJ92K6Qdhsv
uqc1objMrOy0vkbPW9awsE1gqkvRGnpPAAVk4kDLUSI99e2DFqbQgDKPNady3dfz
/4MufV8BvCKigGssB3HnvGHg33I+7Src1SlMFjwwi5sQCU5C/xwRE9HyDz8IG3aS
xJhCx+Lu5F6lc87Ti4z8
=toSm
-----END PGP SIGNATURE-----

[prance...@sigaint.org]

>> I don't think Qubes wants to be "mainstream".

Perhaps mainstream was the wrong word. I meant Qubes aims to be a primary,
versatile laptop/desktop-OS, as opposed to e.g. Tails. Qubes already can
do almost everything most users want to do on their laptops/desktops, it's
just not always clear how to do it. By design, Qubes will never be as
usable as windows, but there's no reason it can't be as accessible as e.g.
debian. Only more comprehensive and up to date documentation stands in the
way, imo.

>> I hate Google, but if you don't trust them use PGP signatures to
>> protect the integrity of your mails.

Good point. I was also remembering Aral Balkan's post about CPDP and
privacy-washing https://ar.al/notes/why-im-not-speaking-at-cpdp/ . It
really emphasizes why google and privacy shouldn't be mixed.

> Thanks to github interface, editing a file there isn't that hard. Take a
> look here:
> https://www.qubes-os.org/doc/doc-guidelines/

Thanks for doing this Marek. That make it a lot clearer.

[Tim W]

That is exactly what I was thinking of when I mentioned improving the doc editing instructions.  Thank you Marek for putting that together and quickly.    For some reason my last post that outlined my ideas/suggestions did not post.  

Somethings I had mentioned were:

A link to a cheat sheet for markdown file syntax.  Not much of an issue for those that have worked html but for those that have not they would not know **text** bolds it.   That is actually one of my biggest qualms with the github online editor is the lack of a tool bar.  That allows those with no knowledge to be able to get working immediately.  Such as how to make a line break using <br> and to not have it format to the lines above a open line is needed.

Here is the link to github hosted cheetsheet in adam-p repo which IMO is quite adequate with links to any additional info needed:  Markdown Here Cheatsheet
 

To the above point,  I found using a local basic markdown text editor much easier (especially being a relative newbie to markdown format and syntax) as it has the above things included.   I briefly evaluated numerous ones.  Some were way more than needed (too complex) for editing or building basic doc pages such as are being used.  Others took a bit of a learning curve.  Others were not free and or closed source.  Some lacked a preview function which IMO is mandatory.   Of those I found ReText to be one of the best options for the task of editing readme and documentation markdown files.  I am sure there are others but maybe just listing this as an example of a choice for people?

ReText:

• Open Source
• In Fedora and most if not all popular distro repositories
• User Friendly (its gui interfaced)
  
• Tool bar with keyboard shortcuts for syntax functions ( image insert, bold, underline, text size, etc)
• Preview and Live mode that is easy to switch between it and edit mode.
  
• Its local to allow saving and to keep other versions of changes.
  

In its simplest use form a person could simply select all text in the edit more and paste it into the ReText make changes and paste it back.  Or more properly download the doc.md file locally and open and edit it.  Then upload and issue the pull. 

I am using ReText to do the updating of the Archlinux template page and it has made the job a good bit easier and quicker.


Another addition, that would expand the Qubes Documentation's reach and usability, I think would be very helpful is to have a downloadable complete Qubes Documentation file as a .pdf or .odt file. I am willing to do the work putting it together etc.   It can be in true instruction manual format with linkable table of contents etc..  Once it is polished and gets approval it might be a good idea to add it to the qubes repo and then could be easily downloaded ( maybe include a link to its locations and availability in the install iso.  To me having a local copy of all the info would be helpful and convenient.  Obviously the live online version would be the most current.   I think locally this would be better than a collection of .md files.  Allowing people to get help if they can not get network connectivity without having to access another internet device source.


Anyways some ideas to consider


Cheers,

Tim

[prance...@sigaint.org]

> That is exactly what I was thinking of when I mentioned improving the doc
> editing instructions. Thank you Marek for putting that together and
> quickly. For some reason my last post that outlined my
> ideas/suggestions
> did not post.
>
> Somethings I had mentioned were:
>
> A link to a cheat sheet for markdown file syntax. Not much of an issue
> for
> those that have worked html but for those that have not they would not
> know
> **text** bolds it. That is actually one of my biggest qualms with the
> github online editor is the lack of a tool bar. That allows those with no
> knowledge to be able to get working immediately. Such as how to make a
> line break using <br> and to not have it format to the lines above a open
> line is needed.
>
> Here is the link to github hosted cheetsheet in adam-p repo which IMO is
> quite adequate with links to any additional info needed: Markdown Here
> Cheatsheet

> <https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet>

>
>
> To the above point, I found using a local basic markdown text editor much
> easier (especially being a relative newbie to markdown format and syntax)
> as it has the above things included. I briefly evaluated numerous ones.
> Some were way more than needed (too complex) for editing or building basic
> doc pages such as are being used. Others took a bit of a learning curve.
> Others were not free and or closed source. Some lacked a preview function
> which IMO is mandatory. Of those I found ReText to be one of the best
> options for the task of editing readme and documentation markdown files.
> I
> am sure there are others but maybe just listing this as an example of a
> choice for people?
>
> ReText:
>
>

> - Open Source
> - In Fedora and most if not all popular distro repositories
> - User Friendly (its gui interfaced)
> - Tool bar with keyboard shortcuts for syntax functions ( image insert,

> bold, underline, text size, etc)

> - Preview and Live mode that is easy to switch between it and edit
> mode.
> - Its local to allow saving and to keep other versions of changes.

Honestly, I've always been surprised that qubes didn't include the
documentation. Some people's life or freedom depends on using qubes
correctly, and having to fire up whonix anytime you want to read the docs
is not ideal. A salt script to configure a doc building template, or just
a doc page with step-by-step instructions for cloning the git repo,
installing required packages and building the docs to odt, pdf, epub would
be a good start. The crypto party handbook has a page on this (although
not the best example as their instructions are out of date and don't work
without editing).

[Qubed One]

Jeremy Rand:

> On 01/27/2016 09:49 PM, Tim W wrote:
>
>> While the github way is certainly not stupid easy like wiki we are
>>

>> (snip)
>>
>
> This exactly.
>
> (snip)

>
> The set of people who are qualified to write Qubes documentation
> safely is a small percentage of the people who will be using it.
> People who cannot understand how to edit a document on GitHub when
> given the right instructions (which as Tim says, could use
> improvement), are unlikely to be qualified to write Qubes
> documentation safely.
>
> Usability is an important attribute to strive for, but let's not brick
> security in the process of gaining a tiny amount of usability. People
> who want that balance are happy on Windows.
>
> Cheers,

> -Jeremy Rand
>


This exactly.