search

smolijar / gitwiki-thesis

The goal of the thesis is to develop an access-controlled wiki system based on Git, with the support of lightweight markup languages. In analysis, the system is defined through the conventional methods. With regard to its requirements, existing open-source wiki systems are reviewed. Solution to their weaknesses are discussed along with the system’s design, according to which it is imple- mented. Finally the automatic testing and the results of the usability testing is commented on.
2 stars 1 forks source link

Finalize description #1

Closed smolijar closed 6 years ago

smolijar commented 7 years ago

See the description

smolijar commented 7 years ago

Konkretni navrhy zmen:

Navrhněte a implementujte wiki systém podporující vícero wiki syntaxí (formou modulů); požadované jsou AsciiDoc a Markdown. Systém bude podporovat ploché jmenné prostory a ACL nastavitelné per jmenný prostor. Jako jediné úložiště bude využívat sadu Git repositářů, což umožní plnohodnotný přístup přes Git. Vedle přímého přístupu přes Git bude poskytovat webové rozhraní umožňující wiki prohlížet, editovat a spravovat. Editor bude pracovat s čistým textem v dané syntaxi (tj. žádný WYSIWYG) a poskytovat živý náhled  vykresleného obsahu. Systém bude použitelný například pro psaní uživatelských příruček či dokumentací a rozšiřitelný pro psaní odborných textů. Při návrhu předpokládejte, že uživatelé znají základy podporované wiki syntaxe. Pro uživatele znalé VCS musí být systém co nejvíce transparentní. Wiki systém implementujte v jazyce Rust, JavaScript/Node.js, Lua, Ruby, nebo Python. Kód musí být srozumitelný a řádně otestovaný.

smolijar commented 7 years ago

@jirutka Je nejaka motivace za volbou jazyku? Neni vhodne zminit v zadani duvody pro povolene/doporucene technologie/jazyky, nebo se k tomu v zadani pristupuje dogmaticky?

jirutka commented 7 years ago

Jako jediné úložiště bude využívat sadu Git repositářů přičemž každý jmenný prostor bude separátní repositář (z důvodu řízení ACL).

"přičemž každý jmenný prostor bude separátní repositář" bych vynechal. Přesto že to bude nejspíš pravda, připadá mi to příliš konkrétní do zadání.

Souhlasím. Nejen, že je to příliš konkrétní, ale když jsem o tom teď více přemýšlel, tak už mi to ani nepřipadá jako příliš dobré řešení.

Wiki systém implementujte v jazyce Rust, JavaScript/Node.js, Lua, Ruby, nebo Python.

Je zde nějaká konkrétní motivace za výběrem jazyků? Jde o Vaši preferenci nebo mají všechny jakzyky nějaký společný rys, který je činí vhodnými pro implementaci? Znám více znám jen JS a Python, s ostatními jsem jen po málu.

Jde pouze o mou preferenci. 😺 Z finálního zdání bych to asi úplně vypustil.

Text ma 964 znaku, myslim, ze strop je 1000 ale nejsem si jisty.

Ano, limit je skutečně 1 000 znaků. 😿

smolijar commented 7 years ago

Omlouvám se za nečinnost poslední dny.

Jazyk

Jde pouze o mou preferenci. :smiley_cat: Z finálního zdání bych to asi úplně vypustil.

Pokud nemáte nic proti, rád bych v zadání zafixoval Js/Node. Myslím, že rešerše bude již dost rozsáhlá, když bude zadán jazyk, platforma.

Transparentnost

Poznamky o uzivateli a jednoduchosti/transparentnosti systemu jsou ponekud vagni ...

Navrhuji zmenu na

Nalzeněte vhodný kompromis, mezi pohodlnou uživatelskou interackí a transparentní sprvou Git repozitárů pro uživatele znalé VCS.

smolijar commented 7 years ago

Odpovedel jsem myslim na vsechny vznesene komentare a prepsal konkretne zadani be7542b22620af421c62aaf0c4bd671dbf8c341e.

Mate prosim k soucasne verzi nejake pripominky @jirutka?

smolijar commented 7 years ago

Krome typo ve transparentní sprvou Git repozitárů :bug:

jirutka commented 7 years ago

No já bych to raději kompletně přepsal. Mám už to rozepsané, jen jsem to chtěl ještě přestrukturovat. Večer to sem hodím.

jirutka commented 7 years ago

Tady je rozepsaná verze:

Navrhněte a implementujte wiki systém zaměřený na technicky zdatné uživatele, který bude použitelný např. jako dokumentační platforma.

Systém bude využívat VCS Git - jako úložiště všech dat i rozhraní pro přístup uživatelů. Jednotlivé wiki stránky budou seskupené do disjunktních jmenných prostorů s jednoduchým systémem řízení práv přístupu. Systém bude podporovat textové značkovací jazyky AsciiDoc a Markdown/CommonMark, s možností doplnění dalších formou modulů.

Vedle přímého přístupu přes Git bude poskytovat webové rozhraní umožňující wiki prohlížet, editovat a spravovat. Editor bude pracovat s textem v daném značkovacím jazyce, se zvýrazněním syntaxe a interaktivní podporou pro vybrané elementy (např. vkládání obrázků). Součástí bude též živý náhled vykresleného obsahu.

smolijar commented 7 years ago

Jedna-li se o rozepsanou verzi, mate @jirutka jeste rozmyslene nejake dalsi upravy, ktere byste chtel zahrnout? Z me strany obsahuje zadani vse dulezite. Rad bych do zadani zakomponoval implementaci v Javascript / Node.js, pokud nemate nic proti tomu.

smolijar commented 7 years ago

Vaší práce na zadání si cením @jirutka, je v mnohem líbivější podobě. Co říkáte na zadání programovacího jazyku?

jirutka commented 6 years ago

Upravený návrh textu zadání:

Cílem práce je vytvořit wiki systém zaměřený na technicky zdatné uživatele, vhodný pro komunitní (softwarové) projekty. Systém musí splňovat tyto vlastnosti:

  • Veškerá data uchovávat v Git repositáři.
  • Nabízet řízení práv přístup s rozlišením čtení/zápis.
  • Podporovat značkovací jazyky AsciiDoc a Markdown, s možností doplnění dalších formou modulů.
  • Umožňovat plnohodnotný uživatelský přístup přes Git a CLI.
  • Poskytovat webové rozhraní pro čtení i editaci. Editor bude pracovat s textem v daném značkovacím jazyce, se zvýrazněním syntaxe, interaktivní podporou pro vybrané elementy (např. vkládání obrázků) a tzv. živým náhledem.

Konkrétně:

  1. Porovnejte nejznámějších F/OSS wiki systémy a zhodnoťte je z pohledu uvedených požadavků.
  2. Navrhněte výše popsaný systém. Uživatelské rozhraní podrobte testování použitelnosti.
  3. Systém implementujte v jazyce JavaScript. Kód musí být rozumně okomentovaný a pokrytý automatizovanými testy.
  4. Napište uživatelskou dokumentaci a postup nasazení.

Co na to říkáš, @grissius? Nějaké připomínky/návrhy? Upozorňuju, že se to musí vejít do 1 000 znaků. :( (Připadal jsem si zase jako při psaní tweetu – polovinu času mi zabralo zkracování.)

smolijar commented 6 years ago

V poradku, je to super. Zkusim sepsat draft zadani v anglictine, abys s tim mel mene prace.

smolijar commented 6 years ago

Create a wiki system suitable for software community projects focused on technically oriented users, which meets the following requirements:

  • System provides access control.
  • System supports AsciiDoc, Markdown and is extensible for other markup languages.
  • Full-featured user access via Git and CLI is provided.
  • System provides web interface for wiki browsing and management. Editor works with raw markup and offers syntax highlight, live preview and interactive UI for selected elements (e.g. image insertion).
  • Git repository is a sole data storage.

Proceed in following manner:

  1. Compare and analyze most popular F/OSS wiki systems with regard to given criteria.
  2. Design said system, perform usability testing.
  3. Implement the system in JavaScript. Source code must be reasonably documented and covered with automatic tests.
  4. Create a user manual and deployment instructions.
jirutka commented 6 years ago

Thanks! I’ve reworded and fixed grammar it a bit:

The goal of this thesis is to create a wiki system suitable for community (software) projects, focused on technically oriented users. The system must meet the following requirements:

  • All data is stored in a Git repository.
  • System provides access control.
  • System supports AsciiDoc and Markdown, it is extensible for other markup languages.
  • Full-featured user access via Git and CLI is provided.
  • System includes a web interface for wiki browsing and management. Its editor works with raw markup and offers syntax highlighting, live preview and interactive UI for selected elements (e.g. image insertion).

Proceed in the following manner:

  1. Compare and analyse the most popular F/OSS wiki systems with regard to the given criteria.
  2. Design the system, perform usability testing.
  3. Implement the system in JavaScript. Source code must be reasonably documented and covered with automatic tests.
  4. Create a user manual and deployment instructions.

WDYT?

smolijar commented 6 years ago

That's my most favorite thesis description 😍

If you are OK with it, will you submit it?

smolijar commented 6 years ago

And before we submit it, the name GitWiki is final? I like it, it's short and descriptive (if you ever heard both words), but sound more like a name of a product rather than a name of an actual thesis, don't you think?

What about expanding the subtitle, like, e.g. GitWiki: Version controlled general purpose wiki system

I admit, the subtitle provides little extra information for those, who get the concept out of the title itself; but for those who don't, you have at least some words in the title itself (like version control and wiki system which at very least implies it's implementation oriented).

@jirutka What are your thoughts on this? If you don't like it and want to keep GitWiki, it's all fine by me. I am not too fond of this. It just popped in head. I am fine either way. 😉

jirutka commented 6 years ago

What about expanding the subtitle, like, e.g. GitWiki: Version controlled general purpose wiki system

This is too long, keep in mind that the title must be printed on spine of the thesis.

What about “Git-based Wiki System”?

I’ve updated the thesis text in IS, it’s currently waiting for your approval.

smolijar commented 6 years ago

Approved. I chose the topic. It still had Czech language and description tho.

All sugested titles are cool with me.